[Numpy-discussion] coding style: citations

[Tim Michelsen]

> If I understand, you are using bib4txt.py to do this?
Yes, I use bib4txt.py.
The extension just runs bib4txt.py over all documents to extract the 
citations. Then it creates the reference file.
The bibtex file is also converted to ReSt using your tools.

But since the bibstuff needs the citation reference to be in a sting 
object, I cannot process the docstrings in order to create the 
literature file with only the referenced citations.
I therefore just include all references as a workaround.

> Then I can offer to help if you run into problems.
The problem above is where you or Georg Brandl or anyone familiar with 
the way Sphinx processes the docstrings works.

> Note that bib4txt can do citation reference substitution.
> I cannot tell if you are doing that separately.
No, I am not doing this.
I create my reference keys in JabRef. The program is cross platform has 
an automatic bibtex key generator which works according to your defined 
pattern.

=> This is just the answer to your question on reference formatting.
The scipy/numpy community just needs to agree on a common reference 
pattern. Say: author_year or authoretal_shorttitle_year and jabref or 
any other program can take care of the rest.

> You did not say specifically what the docstring problem
> is, but the obvious difficulty is the following:
> in a document a reference points to a citation *in that document*,
> while in a docstring it is not clear whether you want that.
> (I.e., should the citation text be in the docstring or
> in a file of citations from all the docstrings?)
Please take a look at the zip file from the bugreport at bitbucket.
I am keen to see what you think. You have more X-perience and may 
suggest some improvements. It comes with a todo / readme.

... nice to see, that my efforts are of use for you.

Kind regards,
Timmie