0
# Citation System
1

2
Regular citation system with global bibliography management across all documents in a project. Citations are resolved globally and typically use a single bibliography directive per project.
3

4
## Capabilities
5

6
### Bibliography Domain
7

8
Main Sphinx domain that manages citation data, bibliography files, and cross-references across all documents.
9

10
```python { .api }
11
class BibtexDomain(Domain):
12
    """
13
    Sphinx domain for the bibtex extension.
14
    
15
    Attributes:
16
        name: str = "cite"
17
        label: str = "BibTeX Citations"
18
        data_version: int = 4
19
    """
20
    
21
    @property
22
    def bibdata(self) -> BibData:
23
        """Information about the bibliography files."""
24
    
25
    @property
26
    def bibliographies(self) -> Dict[BibliographyKey, BibliographyValue]:
27
        """Map storing information about each bibliography directive."""
28
    
29
    @property 
30
    def citations(self) -> List[Citation]:
31
        """Citation data."""
32
        
33
    @property
34
    def citation_refs(self) -> List[CitationRef]:
35
        """Citation reference data."""
36
    
37
    def clear_doc(self, docname: str) -> None:
38
        """Clear document-specific data when document is rebuilt."""
39
        
40
    def merge_domaindata(self, docnames: AbstractSet[str], otherdata: Dict) -> None:
41
        """Merge domain data from parallel builds."""
42
        
43
    def env_updated(self) -> Iterable[str]:
44
        """Process citations after all doctrees are parsed."""
45
        
46
    def resolve_xref(
47
        self,
48
        env: BuildEnvironment,
49
        fromdocname: str,
50
        builder: Builder,
51
        typ: str,
52
        target: str,
53
        node: pending_xref,
54
        contnode: docutils.nodes.Element,
55
    ) -> docutils.nodes.Element:
56
        """Replace citation reference node with formatted citation."""
57
        
58
    def get_all_cited_keys(self, docnames: List[str]) -> Iterable[str]:
59
        """Yield all citation keys for given documents in citation order."""
60
        
61
    def get_entries(self, bibfiles: List[Path]) -> Iterable[Entry]:
62
        """Return all bibliography entries from bib files."""
63
        
64
    def get_filtered_entries(
65
        self, bibliography_key: BibliographyKey
66
    ) -> Iterable[Tuple[str, Entry]]:
67
        """Return bibliography entries filtered by filter expression."""
68
        
69
    def get_formatted_entries(
70
        self,
71
        bibliography_key: BibliographyKey,
72
        docnames: List[str],
73
        tooltips: bool,
74
        tooltips_style: str,
75
    ) -> Iterable[Tuple[Entry, FormattedEntry, Optional[FormattedEntry]]]:
76
        """Get formatted entries with pybtex labels and optional tooltips."""
77
```
78

79
### Bibliography Directive
80

81
Processes the `.. bibliography::` directive to create bibliography sections in documents.
82

83
```python { .api }  
84
class BibliographyDirective(Directive):
85
    """
86
    Class for processing the bibliography directive.
87
    
88
    Options:
89
        cited: Include only cited entries
90
        notcited: Include only non-cited entries  
91
        all: Include all entries
92
        filter: Custom filter expression
93
        style: Bibliography style (overrides default)
94
        list: List type ('citation', 'bullet', 'enumerated')
95
        enumtype: Enumeration type for enumerated lists
96
        start: Start number or 'continue'
97
        labelprefix: Prefix for bibliography labels
98
        keyprefix: Prefix for citation keys
99
    """
100
    
101
    required_arguments: int = 0
102
    optional_arguments: int = 1
103
    has_content: bool = True
104
    
105
    def run(self) -> Sequence[docutils.nodes.Node]:
106
        """
107
        Process .bib files, set file dependencies, and create bibliography node.
108
        
109
        Returns:
110
            List containing bibliography node to be transformed later
111
        """
112
```
113

114
### Citation Role
115

116
Processes inline citation roles like `:cite:p:` and `:cite:t:` in documents.
117

118
```python { .api }
119
class CiteRole(XRefRole):
120
    """
121
    Class for processing the cite role.
122
    
123
    Supports role variants:
124
        :cite:p: - Parenthetical citations: (Author, 2020)
125
        :cite:t: - Textual citations: Author (2020)
126
    """
127
    
128
    def result_nodes(self, document, env, node, is_ref) -> Tuple[List[docutils.nodes.Node], List]:
129
        """
130
        Associate the pending_xref with the cite domain and note citation keys.
131
        
132
        Parameters:
133
            document: Document containing the citation
134
            env: Sphinx build environment
135
            node: Citation reference node
136
            is_ref: Whether this is a reference
137
            
138
        Returns:
139
            Tuple of (nodes, messages)
140
        """
141
```
142

143
### Citation Data Structures
144

145
```python { .api }
146
class CitationRef(NamedTuple):
147
    """Information about a citation reference."""
148
    citation_ref_id: str  # Unique ID of citation reference
149
    docname: str  # Document name where citation appears
150
    line: int  # Line number in document
151
    targets: List[CitationTarget]  # Citation targets (key, pre, post)
152

153
class BibliographyKey(NamedTuple):
154
    """Unique key for each bibliography directive."""
155
    docname: str  # Name of document containing bibliography
156
    id_: str  # ID of bibliography node in document
157

158
class BibliographyValue(NamedTuple):
159
    """Information about a bibliography directive."""
160
    line: int  # Line number of directive
161
    bibfiles: List[Path]  # List of bib files
162
    style: str  # The pybtex style
163
    list_: str  # List type ('citation', 'bullet', 'enumerated')
164
    enumtype: str  # Enumeration type for enumerated lists
165
    start: int  # Start value for enumerated lists
166
    labelprefix: str  # String prefix for pybtex labels
167
    keyprefix: str  # String prefix for citation keys
168
    filter_: ast.AST  # Parsed filter expression
169
    citation_nodes: Dict[str, docutils.nodes.Element]  # Citation nodes by key
170
    keys: List[str]  # Keys listed as directive content
171
```
172

173
## Usage Examples
174

175
### Basic Bibliography
176

177
```restructuredtext
178
See :cite:t:`smith2020` for details on the methodology.
179
Recent studies :cite:p:`jones2019,brown2021` support this approach.
180

181
.. bibliography::
182
```
183

184
### Filtered Bibliography
185

186
```restructuredtext
187
.. bibliography::
188
   :filter: cited and author % "Smith"
189
   :style: plain
190
```
191

192
### Custom List Formats
193

194
```restructuredtext
195
.. bibliography::
196
   :list: enumerated
197
   :enumtype: upperroman
198
   :start: 1
199
```
200

201
### Bibliography with Key Prefixes
202

203
```restructuredtext
204
.. bibliography:: methods.bib
205
   :keyprefix: method-
206
   :labelprefix: M
207
```
208

209
## Filter Expressions
210

211
Bibliography directives support Python-like filter expressions:
212

213
- `cited`: Include only cited entries
214
- `not cited`: Include only non-cited entries  
215
- `author % "pattern"`: Regular expression match on author field
216
- `type == "article"`: Exact match on entry type
217
- `year >= 2020`: Numeric comparison on year field
218
- `docname == "intro"`: Match specific document
219
- `key % "smith.*"`: Pattern match on citation key
220

221
Example complex filter:
222
```restructuredtext
223
.. bibliography::
224
   :filter: cited and (author % "Smith" or year >= 2020) and type != "misc"
225
```