[Numpy-discussion] coding style: citations

[Tim Michelsen]

Hello,
I really like the discussion here.


> Originally I was just pointing out a problem.
> Proposing a good solution requires some discussion.
> The problem has also changed because of a suggestion
> that the docs should be usable for book compilation,
> and I am very uncertain how that is conceived.
> 
> The key question is: should each docstring actually
> contain its citation, or can their be a page of
> citations?
See, many of use may have
a) a folder with all PDF documents of literatures or articles
b) a file which is used to administer the above, be it Bibtex, EndNote, etc.
c) different texts which use a) by the help of b)
d) docstrings with references

In order to unify b) and d) (=reduce doubled work) I decided for keeping 
my citations in one file (references.rst) and reference these from the 
docstrings. This works quite well.

Please have a look at:
http://bitbucket.org/birkenfeld/sphinx/issue/63/make-sphinx-read-bibtex-files-for

And the example Sphinx project at:
#3 - 
http://bitbucket.org/birkenfeld/sphinx/issue/63/make-sphinx-read-bibtex-files-for#comment-3397

I would appreciate very much to receive any feedback on my approach.

Hope that this helps.

Kind regards,
Timmie