0
# Footnote Citations
1
2
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.
3
4
## Capabilities
5
6
### Footnote Bibliography Domain
7
8
Sphinx domain that manages footnote citations locally within each document.
9
10
```python { .api }
11
class BibtexFootDomain(Domain):
12
"""
13
Sphinx domain for footnote citations.
14
15
Attributes:
16
name: str = "footcite"
17
label: str = "BibTeX Footnote Citations"
18
data_version: int = 0
19
"""
20
21
@property
22
def bibliography_header(self) -> docutils.nodes.Element:
23
"""Header element for footnote bibliographies."""
24
25
def merge_domaindata(self, docnames: AbstractSet[str], otherdata: Dict) -> None:
26
"""
27
Merge domain data from parallel builds.
28
29
Note: This domain has no document-specific data to merge.
30
"""
31
32
def resolve_any_xref(
33
self,
34
env: BuildEnvironment,
35
fromdocname: str,
36
builder: Builder,
37
target: str,
38
node: pending_xref,
39
contnode: docutils.nodes.Element,
40
) -> List[Tuple[str, docutils.nodes.reference]]:
41
"""
42
Resolve any cross-reference for footnote citations.
43
44
Returns:
45
Empty list since footnote citations don't use regular xrefs
46
"""
47
```
48
49
### Footnote Bibliography Directive
50
51
Processes the `.. footbibliography::` directive to insert footnote bibliographies created by footnote citation roles.
52
53
```python { .api }
54
class FootBibliographyDirective(Directive):
55
"""
56
Class for processing the footbibliography directive.
57
58
This directive has no options or content - it simply inserts
59
the footnotes that were created by footcite roles earlier
60
in the document.
61
"""
62
63
required_arguments: int = 0
64
optional_arguments: int = 0
65
has_content: bool = False
66
67
def run(self) -> List[docutils.nodes.Node]:
68
"""
69
Set file dependencies and insert footnotes created by FootCiteRole.
70
71
Returns:
72
List containing the footnote bibliography container node,
73
or empty list if no footnotes were created
74
"""
75
```
76
77
### Footnote Citation Role
78
79
Processes inline footnote citation roles like `:footcite:p:` and `:footcite:t:` in documents.
80
81
```python { .api }
82
class FootCiteRole(SphinxRole):
83
"""
84
Class for processing the footcite role.
85
86
Supports role variants:
87
:footcite:p: - Parenthetical footnote citations
88
:footcite:t: - Textual footnote citations
89
"""
90
91
def run(self) -> Tuple[List[docutils.nodes.Node], List[docutils.nodes.system_message]]:
92
"""
93
Transform citation into footnote references and add footnotes to temp data.
94
95
Creates footnote nodes for new citations and stores them in the
96
environment's temporary data for later insertion by FootBibliographyDirective.
97
98
Returns:
99
Tuple of (footnote reference nodes, system messages)
100
"""
101
```
102
103
## Usage Examples
104
105
### Basic Footnote Citations
106
107
```restructuredtext
108
See Smith\ :footcite:t:`smith2020` for details on the methodology.
109
Recent studies support this approach\ :footcite:p:`jones2019,brown2021`.
110
111
.. footbibliography::
112
```
113
114
Note the use of backslash-escaped spaces (`\ `) to prevent unwanted spacing before footnote markers.
115
116
### Multiple Footnote Bibliographies
117
118
Since footnote citations are document-local, you can have multiple bibliography sections:
119
120
```restructuredtext
121
Section 1 discusses early work\ :footcite:p:`early2010,pioneer2012`.
122
123
.. footbibliography::
124
125
Section 2 covers recent advances\ :footcite:p:`recent2020,latest2021`.
126
127
.. footbibliography::
128
```
129
130
### Mixed Regular and Footnote Citations
131
132
You can use both citation systems in the same document:
133
134
```restructuredtext
135
The main methodology :cite:t:`mainmethod2020` is well established.
136
However, some details\ :footcite:p:`detail2019` require clarification.
137
138
.. footbibliography::
139
140
.. bibliography::
141
```
142
143
## Behavior Differences
144
145
### Local vs Global Resolution
146
147
- **Regular citations** (`:cite:`): Resolved globally across all documents
148
- **Footnote citations** (`:footcite:`): Resolved locally within each document
149
150
### Bibliography Placement
151
152
- **Regular bibliography**: Typically one per project, collects all cited references
153
- **Footnote bibliography**: One per document section, shows only local footnotes
154
155
### Citation Numbering
156
157
- **Regular citations**: Use bibliography style labeling (e.g., `[Smith20]`, `[1]`)
158
- **Footnote citations**: Use document footnote numbering (e.g., `[1]`, `[2]`)
159
160
### Duplicate Handling
161
162
- **Regular citations**: Warns about duplicate citation keys across project
163
- **Footnote citations**: No duplicate concerns since citations are document-local
164
165
## Advanced Usage
166
167
### Custom Footnote ID Templates
168
169
```python
170
# conf.py
171
bibtex_footcite_id = "fn-{key}"
172
bibtex_footbibliography_id = "footbib-{footbibliography_count}"
173
```
174
175
### Footnote Bibliography Headers
176
177
```python
178
# conf.py
179
bibtex_footbibliography_header = "**Document References**"
180
```
181
182
### Integration with Document Structure
183
184
Footnote bibliographies work well with document sections:
185
186
```restructuredtext
187
Chapter 1: Introduction
188
=======================
189
190
Content with citations\ :footcite:p:`intro2020`.
191
192
.. footbibliography::
193
194
Chapter 2: Methods
195
==================
196
197
Methods content\ :footcite:p:`methods2021`.
198
199
.. footbibliography::
200
```
201
202
## Error Handling
203
204
- **Missing bibliography keys**: Warns about unfound keys, continues processing
205
- **No footnotes**: `footbibliography` directive returns empty content if no citations
206
- **Style errors**: Uses default formatting if footnote style configuration is invalid