`foot` style in `bibtex_reference_style`

[MLopez-Ibanez]

The super and foot styles differ in a few details:

• super does not have brackets, foot does.
• Even if we add brackets to super by customizing (see below), the brackets are not hyperlinked, unlike foot style.

Thus, to achieve a consistent style when using both cite and footcite, it would be great to be able to use foot in bibtex_reference_style.

from dataclasses import dataclass, field
from sphinxcontrib.bibtex.style.referencing import BracketStyle,PersonStyle
from sphinxcontrib.bibtex.style.referencing.super_ import SuperReferenceStyle
from sphinxcontrib.bibtex.plugin import register_plugin as sphinxcontrib_register_plugin

@dataclass
class SuperWithBrackets(SuperReferenceStyle):
    #: Bracket style for textual citations (:cite:t: and variations).
    bracket_textual: BracketStyle = field(default_factory=BracketStyle)

    #: Person style (applies to all relevant citation commands).
    person: PersonStyle = field(default_factory=PersonStyle)

sphinxcontrib_register_plugin('sphinxcontrib.bibtex.style.referencing',
                              'super_with_brackets', SuperWithBrackets)

[mcmtroffaes]

Thanks for reporting. I'm unsure what is the ask here, but what you've done with super_with_brackets seems sensible, and this is exactly how you should use the extension.

However, there are several problems (some of which out of scope of sphinxcontrib-bibtex...):

• Whilst for individual use cases, it may be possible to achieve similar styles, the html and LaTeX rendering of footnotes is very different (this is down to how Sphinx/docutils render footnotes, and is not unique to this extension): one uses brackets whilst the other does not.
• The lack of backreferences that you observe in citation references is because Sphinx does not generate backlinks to citations whose citation is in a different document than their citation reference. This limitation is a problem with all Sphinx citations (not just those generated by sphinxcontrib-bibtex).
• The super style does not generate footnotes, so calling it "foot" seems inappropriate to me (but super_with_brackets would be fine).
• I prefer steer away from having many built-in custom styles besides the basic ones, since it is easy to customize from within conf.py (as you have done excellently).

[MLopez-Ibanez]

OK, fair enough, but it would be useful to have more examples in the documentation or in a contrib/ folder. I tried and failed to get the whole string "[1]" hyperlinked, not just the "1".

Even my solution is not working well. It seems to work for :cite:t: but not for :cite:p: as you can see if you compare the first citations to '2' and '3' here: https://multi-objective.github.io/moocore/python/reference/functions.metrics.html#inverted-generational-distance-igd-and-igd-and-averaged-hausdorff-distance.

A few clarifications:

• I am only talking about HTML output, not LaTeX.
• I don't mind not having backlinks (for now).
• You are right that the super style does not generate footnote directives. Perhaps I am using :footcite: to solve a problem that was not designed to solve: How to have per page bibliographies? Similar to what multibib (https://www.overleaf.com/learn/latex/Multibib) or chapterbib (https://ctan.org/pkg/chapterbib?lang=en) achieve in LaTeX. With that goal, it becomes desirable to make citations and bibliographies look as similar as possible, independently of whether they are global or per-page/section. Maybe it is too much to ask of sphinx...

[mcmtroffaes]

To have brackets in both :cite:t: and :cite:p: in the super style you need something like this (untested):

@dataclass
class SuperWithBrackets(SuperReferenceStyle):
    bracket_textual: BracketStyle = field(default_factory=BracketStyle)
    bracket_parenthetical: BracketStyle = field(default_factory=BracketStyle)

Happy to add this as an example somewhere.

The :footcite: system generates standard footnotes and is designed specifically for per-page local bibliographies (per html page for the html builder, and per physical page for the latex builder). The :cite: system generates standard docutils/sphinx citations. Mixing the two will result in some confusion... (same as with latex, you wouldn't normally use both footnotes and standard citations in the same document to manage your citations).

Hyperlinking the whole string is not how the formatting currently works because multiple citation keys can be bundled within the same :cite:, giving for instance [1,2,3,4]. So the brackets and commas are not linked. This is different from footnotes which are inserted directly as is.

Anyway, I hope my code example helps, and that I've clarified everything for you concerning how sphinxcontrib-bibtex is meant to be used, and its hard limitations. I'm sorry it could not do everything you expected.

Let me know if you have any further questions/thoughts.