:cite:ref1,ref2 : put the two references in the same bracket?

[xuhdev]

Maybe this is my bias, but when I wrote :cite:ref1,ref2`` I would expect something like the following output:

[ref1,ref2]

instead of [ref1][ref2]. [ref1,ref2] looks common in papers --- when people want [ref1][ref2], they put them into two different cites. Can we make the change in this extension? Thanks!

[mcmtroffaes]

If you're familiar with latex, then yes that's a sensible suggestion. However, does sphinx supports this for standard docutils citations? I think not (but if I'm wrong, tell me!), so this would have to be implemented into upstream sphinx first. I'm not sure how that would have to work, as docutils itself also doesn't support this sort of formatting out of the box. So it's probably possible, but it probably also takes quite a lot of upstream work and convincing.

[xuhdev]

@mcmtroffaes Can you tell me what is the standard docutils citation?

[mcmtroffaes]

Simply something like:

Here's a standard restructured text citation [CIT2002]_.

.. [CIT2002] Title, author, year...

The sphinxcontrib-bibtex extension essentially converts :cite: commands and bibliography directives into this format, so anything that format supports, the extension can support. The point I was trying to make was that standard restructured text does not support things like [CIT2002,CIT2008].

[mcmtroffaes]

Also see http://docutils.sourceforge.net/docs/user/rst/quickref.html#citations

[xuhdev]

@mcmtroffaes Thanks for your explanation. I tried to include two citations in a bracket, the following seems working:

[this_, that_]

.. [this] here
.. [that] there

In my opinion, this is enough to implement the features. What do you think?

[mcmtroffaes]

Thanks for looking into what we can do with docutils. I think these are not citations but regular references; does the latex backend produce an actual bibliography for these?

[mcmtroffaes]

Oh actually reading the docs they are citations. 💃 I wonder whether this will jive well with latex; I suspect it may just produce something like [[this], [that]] which is probably not what you want... :-/

[xuhdev]

I've verified that the LaTeX output is consistent with the html output :-)

[mcmtroffaes]

Many thanks for doing the research. It looks like you uncovered a deep undocumented feature of docutils, pretty impressive! ;-) I'll try to see if I can find out how to generate the proper nodes in docutils to achieve the same effect with the extension.

[xuhdev]

@mcmtroffaes This feature is actually documented in the example here -- see the final "this" in the example.

[xuhdev]

@mcmtroffaes It seems that sphinx explicitly transforms any citation reference to the bracket format:
https://github.com/sphinx-doc/sphinx/blob/master/sphinx/transforms.py#L160

Is it possible to generate pending_xref directly?

[mcmtroffaes]

Great find! Yes, maybe that's exactly what we should do. I'm a bit hesitant to override any of sphinx's clever magic, but if we can somehow "inject" our own transforms, that would be pretty cool. Judging from the priority on Sphinx's transform, if we add one at priority 618, that should do the trick. There's nothing at that priority in Sphinx at the moment:

https://github.com/sphinx-doc/sphinx/search?utf8=%E2%9C%93&q=618&type=Code

[hughchristensen]

@mcmtroffaes @xuhdev did you get anywhere with this? We would also like to be able to represent multiple citations as [i,j,k,...]

[dahlend]

Bringing this back from 3.5 years in the past.
We are also interest in this, in one instance we have more than 10 references in a chain, and something like [1-10] would be fantastic, but at this point I would take [1, 2, 3, etc]

[mcmtroffaes]

Glad to report this has now been implemented as part of #219 which hopefully will get merged soon. That PR switches to our own fully custom node generation rather than relying on docutils/sphinx to manipulate the doctree and resolve references, making this feature request easy to implement.