tessl/pypi-sphinxcontrib-bibtex
Sphinx extension for BibTeX style citations.
footnote-citations.mddocs/
Footnote Citations
Local footnote-based citations that are resolved per document, useful for per-document bibliographies. Unlike regular citations, footnote citations are document-local and can have multiple bibliography sections per document.
Capabilities
Footnote Bibliography Domain
Sphinx domain that manages footnote citations locally within each document.
class BibtexFootDomain(Domain):
"""
Sphinx domain for footnote citations.
Attributes:
name: str = "footcite"
label: str = "BibTeX Footnote Citations"
data_version: int = 0
"""
@property
def bibliography_header(self) -> docutils.nodes.Element:
"""Header element for footnote bibliographies."""
def merge_domaindata(self, docnames: AbstractSet[str], otherdata: Dict) -> None:
"""
Merge domain data from parallel builds.
Note: This domain has no document-specific data to merge.
"""
def resolve_any_xref(
self,
env: BuildEnvironment,
fromdocname: str,
builder: Builder,
target: str,
node: pending_xref,
contnode: docutils.nodes.Element,
) -> List[Tuple[str, docutils.nodes.reference]]:
"""
Resolve any cross-reference for footnote citations.
Returns:
Empty list since footnote citations don't use regular xrefs
"""Footnote Bibliography Directive
Processes the .. footbibliography:: directive to insert footnote bibliographies created by footnote citation roles.
class FootBibliographyDirective(Directive):
"""
Class for processing the footbibliography directive.
This directive has no options or content - it simply inserts
the footnotes that were created by footcite roles earlier
in the document.
"""
required_arguments: int = 0
optional_arguments: int = 0
has_content: bool = False
def run(self) -> List[docutils.nodes.Node]:
"""
Set file dependencies and insert footnotes created by FootCiteRole.
Returns:
List containing the footnote bibliography container node,
or empty list if no footnotes were created
"""Footnote Citation Role
Processes inline footnote citation roles like :footcite:p: and :footcite:t: in documents.
class FootCiteRole(SphinxRole):
"""
Class for processing the footcite role.
Supports role variants:
:footcite:p: - Parenthetical footnote citations
:footcite:t: - Textual footnote citations
"""
def run(self) -> Tuple[List[docutils.nodes.Node], List[docutils.nodes.system_message]]:
"""
Transform citation into footnote references and add footnotes to temp data.
Creates footnote nodes for new citations and stores them in the
environment's temporary data for later insertion by FootBibliographyDirective.
Returns:
Tuple of (footnote reference nodes, system messages)
"""Usage Examples
Basic Footnote Citations
See Smith\ :footcite:t:`smith2020` for details on the methodology.
Recent studies support this approach\ :footcite:p:`jones2019,brown2021`.
.. footbibliography::Note the use of backslash-escaped spaces (\ ) to prevent unwanted spacing before footnote markers.
Multiple Footnote Bibliographies
Since footnote citations are document-local, you can have multiple bibliography sections:
Section 1 discusses early work\ :footcite:p:`early2010,pioneer2012`.
.. footbibliography::
Section 2 covers recent advances\ :footcite:p:`recent2020,latest2021`.
.. footbibliography::Mixed Regular and Footnote Citations
You can use both citation systems in the same document:
The main methodology :cite:t:`mainmethod2020` is well established.
However, some details\ :footcite:p:`detail2019` require clarification.
.. footbibliography::
.. bibliography::Behavior Differences
Local vs Global Resolution
- Regular citations (
:cite:): Resolved globally across all documents - Footnote citations (
:footcite:): Resolved locally within each document
Bibliography Placement
- Regular bibliography: Typically one per project, collects all cited references
- Footnote bibliography: One per document section, shows only local footnotes
Citation Numbering
- Regular citations: Use bibliography style labeling (e.g.,
[Smith20],[1]) - Footnote citations: Use document footnote numbering (e.g.,
[1],[2])
Duplicate Handling
- Regular citations: Warns about duplicate citation keys across project
- Footnote citations: No duplicate concerns since citations are document-local
Advanced Usage
Custom Footnote ID Templates
# conf.py
bibtex_footcite_id = "fn-{key}"
bibtex_footbibliography_id = "footbib-{footbibliography_count}"Footnote Bibliography Headers
# conf.py
bibtex_footbibliography_header = "**Document References**"Integration with Document Structure
Footnote bibliographies work well with document sections:
Chapter 1: Introduction
=======================
Content with citations\ :footcite:p:`intro2020`.
.. footbibliography::
Chapter 2: Methods
==================
Methods content\ :footcite:p:`methods2021`.
.. footbibliography::Error Handling
- Missing bibliography keys: Warns about unfound keys, continues processing
- No footnotes:
footbibliographydirective returns empty content if no citations - Style errors: Uses default formatting if footnote style configuration is invalid
Install with Tessl CLI
npx tessl i tessl/pypi-sphinxcontrib-bibtex