local bibliographies

[mcmtroffaes]

Reported over email by @chebee7i

I've played
briefly with your package, and the biggest issue I ran into is that it seems
to be painful to have local bibliographies per docstring or rst file.

That is, if I put:

.. bibliography:: ../references.bib
:cited:

at the end of a docstring or ReST file, then it is including all cited
references throughout all docstrings and ReST files. I've seen the stuff
for filtrations, but this is really a lot of work.

Yes, a filter just for local stuff would seem highly inappropriate...

So is it easy to have :local: citations only? I still want to construct a
global bibliography, but I'd like to be able to have many different
docstrings cite the same reference, possibly multiple times, and have local
and global bibliographies.

That sounds like an attractive feature - I'll look into it! Per document is probably quite easy to implement. Per docstring seems tricky - I'd have to look into Sphinx's autodoc extension to see if I can somehow hook into it.

Aside, an obvious problem with multiple bibliographies is: sphinx does not allow duplicate citations (and currently I cannot easily work around that...), so where should citations point to (this is the same in latex...)? But you could have a local citation list with normal global citations, or the other way around.

[chebee7i]

Here's one way to handle it LaTeX only: http://tex.stackexchange.com/questions/142632/multiple-bibliographies-with-local-links-global-labels-also-global-bibliograph

[mcmtroffaes]

Thanks, that provides some inspiration.

[bk322]

By default, bibliographies include everything cited anywhere in the document (as in standard LaTeX). One way to override this would be to use filtering

I'll try that, thanks.

A possibly simpler way to achieve what you want is to use different bib files per document (assuming you do not have overlapping citations).

I do have overlaping citations. I cite same paper for different statements.

you have your bib file in your _static folder, but this file is not needed online to render the bibliography. I guess you need to have the bib file online for another reason?

Nope, no reason. Probably should keep bib files in _bib.

[bk322]

I tried the filter approach: it doesn't work when I have a paper which is refereneced in the other part of the document. In this case numbring get confused, and I get multiple items in the bibliography with the same number.

[mcmtroffaes]

Yes, that's expected. Sphinx does not like duplicate citation entries across different documents (neither does LaTeX FWIW, at least not without special purpose packages). Quoting from the documentation: "Sphinx will attempt to resolve references to the bibliography across all documents, so you must take care that no citation key is included more than once."

[bk322]

Sphinx does not like duplicate citation entries across different documents (neither does LaTeX FWIW, at least not without special purpose packages).

That's not the case. I do not have multiple bib keys with the same name. I just quote same paper in multiple places, and than when I apply filter -- the numbering gets confused. LaTeX numbering doesn't get confused in this case.

Sphinx will attempt to resolve references to the bibliography across all documents, so you must take care that no citation key is included more than once.

This suggests a workaround. I can have multiple bib entries for each citation. This solves the multiple references issue. And also filter to get consecuting numbering starting with 1 in each rst page.

This workaround defeats the purpose of bibliograpy managment in a way, but allows for a formatted references.

[mcmtroffaes]

Just to note here that coding progress of this feature is tracked in pull request #63.

[mcmtroffaes]

Pull request merged, so closing.

[mcmtroffaes]

Just to note here that a better solution is in the works (hopefully to be released with 0.3.3).

• discussion: Support docstring local bibliographies #87
• pull request: Support bibliography key prefixes. #88