numbering and multiple item problem when citing from multiple documents

[mcmtroffaes]

Reported by @bk322 - forked from issue #52

[mcmtroffaes]

@bk322 Sorry for not responding faster. It sounds like you ran into a bug. Do you have a repository somewhere that demonstrates the numbering and multiple item problem?

[bk322]

Sorry, busy week here. I just uploaded a zip of an example doc which illustrates the problems:

• bibliography lists all the items cited in the doc, not just items cited on a page
• numbering is wrong

Link: http://dl.dropbox.com/u/61989972/Misc/sphinxcontrib-bibtex.zip

[mcmtroffaes]

Thanks for the test case @bk322 - I'll look into this ASAP.

[mcmtroffaes]

You need to use the filter option (as mentioned in #52) and the labelprefix option (or use the alpha style, requires pybtex 0.17):

https://github.com/mcmtroffaes/sphinxcontrib-bibtex-test-issue-62/compare/5afac...master [edit: fixed commit link]

(Of course, ideally there should be a much better way to deal with local bibliographies. Sphinx does not support this out of the box unfortunately. However there might be a simple way to implement filtering on the document name... I'm looking into this.)

[mcmtroffaes]

@bk322 I used your test files to create a test case in the library for the new filtering method, making it easier to create local bibliographies:

https://github.com/mcmtroffaes/sphinxcontrib-bibtex/commit/7ba16e305d55eea79bc9bb3fee21bf59cad0d6db

There you can also see how the local filtering system will work (actually, it's filtering on document name; that's enough to allow local bibliographies, but it is also more extensible).

Please let me know if you have a problem with using the code that you provided - I can very easily change the text and references if need be.

[bk322]

Doesn't work for me: result is almost the same. Or did I do something wrong?

[mcmtroffaes]

Ah, I should have mentioned that you will need the feature/local-bibliographies branch of sphinxcontrib-bibtex for this to work (you can track the progress of that branch in pull request #63). Your result seems to be what you would get with the develop branch. I'm holding off to merge it into develop until the feature is fully documented.

Aside, I'm thinking to add "docname" as another keyword that can be used in filters, returning the current document name, so local bibliographies can be created simply with

... bibliography:: refs.bib
    :filter: docname in docnames

rather than having to specify the document name explicitly as in:

... bibliography:: refs.bib
    :filter: "doc1" in docnames

Please let me know if you have any further suggestions for this feature.

[bk322]

Thanks. I think docname is a good idea. Will I be able to get bibliographies without labelprefix? I'd prefer for a plain numbering within a given rst file.

[mcmtroffaes]

That's a reasonable request (particularly if you come from LaTeX). At the moment, there are at least two reasons as to why plain global numbering is tricky to implement, and perhaps even undesirable for very large projects.

First, sphinx may parse documents in arbitrary order (unlike, say, latex, which only produces a single pdf file so ordering is not ambiguous), so a consistent global numbering is non-trivial.

Secondly, a global numbering would also create a dependency chain between documents. Actually, due to the interaction with pybtex, it might even be that all documents would need to become dependent on each other, because pybtex does not work "incrementally" at the moment. So repeated invokations of Sphinx builds would potentially get a lot slower: all documents that have citations or bibliographies would need to be recompiled as soon as one such document changes.

If you don't want to use :labelprefix: X, try :style: alpha; alpha labels are usually unique enough to avoid clashes.

[bk322]

Thanks for a quick reply. I meant I'd prefer plain numbering per document (rst-file), not the global numbering. So that each sphinx page might be read independently, just like blog entries.

[mcmtroffaes]

Yes, that works: just ignore the "duplicate label for keys" warnings. The "duplicate citation" warnings should not be ignored (at the moment); Sphinx will get horribly confused if this happens. I haven't thought yet about how to fix at least the labels in this case...

[mcmtroffaes]

Code for improved local bibliographies is now merged, so closing.

[bk322]

Thank You so much. It works wonderfully. I just checked the default style (alpha). Now I switched to plain... how do I remove cache? Is there a way to turn off caching? (I like the idea that everything related to a document is under the document dir)

[mcmtroffaes]

I'm glad you got it working.

I'm not sure about your question regarding the cache... Sphinx caches each compiled document so subsequent compilations only need to compile changed documents - is it this you want to turn off? If so, simply remove the _build folder prior to your build to force a full recompile.