0
# Sphinxcontrib Bibtex
1

2
A Sphinx extension that enables BibTeX-style citation support for Sphinx documentation projects. It allows developers to insert bibliographic citations into their documentation using BibTeX files through bibliography directives and citation roles, similar to LaTeX's citation system.
3

4
## Package Information
5

6
- **Package Name**: sphinxcontrib-bibtex
7
- **Package Type**: Sphinx extension
8
- **Language**: Python
9
- **Installation**: `pip install sphinxcontrib-bibtex`
10

11
## Core Imports
12

13
```python
14
# Main extension setup function
15
from sphinxcontrib.bibtex import setup
16

17
# Core classes for advanced usage (not typically needed by end users)
18
from sphinxcontrib.bibtex.domain import BibtexDomain, Citation
19
from sphinxcontrib.bibtex.directives import BibliographyDirective, BibliographyKey, BibliographyValue
20
from sphinxcontrib.bibtex.roles import CiteRole
21
from sphinxcontrib.bibtex.foot_roles import FootCiteRole
22
from sphinxcontrib.bibtex.bibfile import BibData, BibFile
23
from sphinxcontrib.bibtex.citation_target import CitationTarget
24
from sphinxcontrib.bibtex.nodes import bibliography, raw_latex
25
from sphinxcontrib.bibtex.transforms import BibliographyTransform, node_text_transform
26
```
27

28
## Basic Usage
29

30
### Extension Configuration
31

32
Add to your Sphinx `conf.py`:
33

34
```python
35
extensions = ['sphinxcontrib.bibtex']
36
bibtex_bibfiles = ['refs.bib']
37
```
38

39
### Citation Usage in Documents
40

41
```restructuredtext
42
See :cite:t:`1987:nelson` for an introduction to non-standard analysis.
43
Non-standard analysis is fun :cite:p:`1987:nelson`.
44

45
.. bibliography::
46
```
47

48
With footnote citations:
49

50
```restructuredtext
51
See :footcite:t:`1987:nelson` for an introduction to non-standard analysis.
52
Non-standard analysis is fun\ :footcite:p:`1987:nelson`.
53

54
.. footbibliography::
55
```
56

57
## Architecture
58

59
The extension follows Sphinx's domain-based architecture:
60

61
- **Domains**: `BibtexDomain` manages global citations, `BibtexFootDomain` manages footnote citations
62
- **Directives**: `BibliographyDirective` and `FootBibliographyDirective` process bibliography blocks
63
- **Roles**: `CiteRole` and `FootCiteRole` process inline citations
64
- **Transforms**: `BibliographyTransform` converts bibliography nodes to formatted citations
65
- **Style System**: Pluggable referencing and formatting styles based on pybtex
66

67
## Capabilities
68

69
### Extension Setup and Configuration
70

71
Core extension setup function and configuration system that integrates with Sphinx's configuration framework.
72

73
```python { .api }
74
def setup(app: Sphinx) -> Dict[str, Any]:
75
    """Set up the bibtex extension with Sphinx application."""
76
```
77

78
[Configuration](./configuration.md)
79

80
### Citation System
81

82
Regular citation system with global bibliography management across all documents in a project.
83

84
```python { .api }
85
class BibtexDomain(Domain):
86
    """Sphinx domain for bibtex citations."""
87
    
88
class BibliographyDirective(Directive):
89
    """Processes the bibliography directive."""
90
    
91
class CiteRole(XRefRole):
92
    """Processes cite roles like :cite:p: and :cite:t:."""
93
```
94

95
[Citation System](./citation-system.md)
96

97
### Footnote Citation System
98

99
Local footnote-based citations that are resolved per document, useful for per-document bibliographies.
100

101
```python { .api }
102
class BibtexFootDomain(Domain):
103
    """Sphinx domain for footnote citations."""
104
    
105
class FootBibliographyDirective(Directive):
106
    """Processes the footbibliography directive."""
107
    
108
class FootCiteRole(SphinxRole):
109
    """Processes footcite roles like :footcite:p: and :footcite:t:."""
110
```
111

112
[Footnote Citations](./footnote-citations.md)
113

114
### Bibliography File Processing
115

116
BibTeX file parsing, caching, and processing functionality built on pybtex.
117

118
```python { .api }
119
class BibData(NamedTuple):
120
    """Information about collection of bib files."""
121
    encoding: str
122
    bibfiles: Dict[Path, BibFile]
123
    data: BibliographyData
124

125
def parse_bibdata(bibfilenames: List[Path], encoding: str) -> BibData:
126
    """Parse bibliography files with given encoding."""
127

128
def process_bibdata(bibdata: BibData, bibfilenames: List[Path], encoding: str) -> BibData:
129
    """Parse and cache bibliography data."""
130
```
131

132
[Bibliography Processing](./bibliography-processing.md)
133

134
### Style and Formatting System
135

136
Pluggable style system for citation formatting and referencing, supporting multiple citation styles.
137

138
```python { .api }
139
class BaseReferenceStyle(ABC):
140
    """Base class for citation reference styles."""
141
    
142
def format_references(
143
    style: BaseReferenceStyle,
144
    role_name: str,
145
    references: Iterable[Tuple[Entry, FormattedEntry, ReferenceInfo]]
146
) -> BaseText:
147
    """Format references according to given style."""
148
```
149

150
[Style System](./style-system.md)
151

152
### Document Nodes and Transforms
153

154
Internal document tree nodes and transform classes for processing bibliography elements during Sphinx document generation.
155

156
```python { .api }
157
class bibliography(nodes.General, nodes.Element):
158
    """Node for representing a bibliography in the document tree."""
159
    
160
class BibliographyTransform(SphinxPostTransform):
161
    """Transform to generate citation entries for bibliography nodes."""
162
    default_priority: int = 5
163
    
164
def node_text_transform(node: docutils.nodes.Element) -> None:
165
    """Apply extra text transformations to a document node."""
166
```
167

168
[Nodes and Transforms](./nodes-transforms.md)
169

170
## Types
171

172
```python { .api }
173
class Citation(NamedTuple):
174
    """Information about a citation."""
175
    citation_id: str
176
    bibliography_key: BibliographyKey
177
    key: str
178
    entry: Entry
179
    formatted_entry: FormattedEntry
180
    tooltip_entry: Optional[FormattedEntry]
181

182
class CitationTarget(NamedTuple):
183
    """Citation key with pre-text and post-text."""
184
    key: str
185
    pre: str
186
    post: str
187

188
class BibliographyKey(NamedTuple):
189
    """Unique key for each bibliography directive."""
190
    docname: str
191
    id_: str
192

193
class BibFile(NamedTuple):
194
    """Information about a parsed bib file."""
195
    mtime: float
196
    keys: Dict[str, None]
197

198
class BibliographyValue(NamedTuple):
199
    """Information about a bibliography directive."""
200
    line: int
201
    bibfiles: List[Path]
202
    style: str
203
    list_: str
204
    enumtype: str
205
    start: int
206
    labelprefix: str
207
    keyprefix: str
208
    filter_: ast.AST
209
    citation_nodes: Dict[str, docutils.nodes.Element]
210
    keys: List[str]
211
```