0
# Nodes and Transforms
1

2
Document tree nodes and transforms for processing bibliography elements in Sphinx documents. These components handle the internal representation and processing of bibliography and citation elements.
3

4
## Capabilities
5

6
### Document Nodes
7

8
Custom docutils nodes for representing bibliographic elements in the document tree.
9

10
```python { .api }
11
class bibliography(nodes.General, nodes.Element):
12
    """
13
    Node for representing a bibliography in the document tree.
14
    
15
    This node is created by BibliographyDirective and later replaced by
16
    a list of citations by BibliographyTransform during post-processing.
17
    
18
    Inherits from:
19
        nodes.General: General document element
20
        nodes.Element: Base element class
21
    """
22

23
class raw_latex(nodes.Special, nodes.Inline, nodes.PreBibliographic, nodes.FixedTextElement):
24
    """
25
    Node for representing raw LaTeX data in documents.
26
    
27
    Used for LaTeX-specific formatting that should be passed through
28
    directly to LaTeX output without processing.
29
    
30
    Inherits from:
31
        nodes.Special: Special formatting element
32
        nodes.Inline: Inline element
33
        nodes.PreBibliographic: Element that appears before bibliography
34
        nodes.FixedTextElement: Element with fixed text content
35
    """
36
```
37

38
### LaTeX Node Visitors
39

40
Functions for handling LaTeX output of custom nodes during document generation.
41

42
```python { .api }
43
def visit_raw_latex(self: LaTeXTranslator, node: raw_latex) -> None:
44
    """
45
    Called when entering a raw_latex node during LaTeX translation.
46
    
47
    Appends the node's raw source directly to the LaTeX body without
48
    any processing or escaping.
49
    
50
    Parameters:
51
        self: LaTeX translator instance
52
        node: The raw_latex node being processed
53
        
54
    Side Effects:
55
        Appends node.rawsource to self.body
56
    """
57

58
def depart_raw_latex(self: LaTeXTranslator, node: raw_latex) -> None:
59
    """
60
    Called when leaving a raw_latex node during LaTeX translation.
61
    
62
    This function performs no action as all processing is done
63
    in visit_raw_latex.
64
    
65
    Parameters:
66
        self: LaTeX translator instance  
67
        node: The raw_latex node being processed
68
    """
69
```
70

71
### Bibliography Transform
72

73
Post-transform that converts bibliography nodes into formatted citation lists.
74

75
```python { .api }
76
class BibliographyTransform(SphinxPostTransform):
77
    """
78
    Docutils transform to generate citation entries for bibliography nodes.
79
    
80
    This transform runs after all documents are parsed but before cross-references
81
    are resolved. It converts bibliography nodes into formatted citation lists
82
    based on the citations that were collected during parsing.
83
    
84
    Attributes:
85
        default_priority: int = 5  # Runs before ReferencesResolver (priority 10)
86
        backend: Backend instance for rendering formatted entries
87
    """
88
    
89
    def run(self, **kwargs) -> None:
90
        """
91
        Transform each bibliography node into a list of citations.
92
        
93
        For each bibliography node in the document:
94
        1. Retrieves the associated bibliography configuration
95
        2. Gets all citations that belong to this bibliography  
96
        3. Creates appropriate citation nodes (enumerated, bullet, or citation list)
97
        4. Formats each citation using pybtex backend
98
        5. Replaces the bibliography node with the formatted citation list
99
        
100
        Parameters:
101
            **kwargs: Additional keyword arguments (unused)
102
            
103
        Side Effects:
104
            - Modifies document tree by replacing bibliography nodes
105
            - Updates environment temp data for enumerated list counters
106
        """
107
```
108

109
### Text Processing Utilities
110

111
Utility functions for processing and transforming text content in nodes.
112

113
```python { .api }
114
def node_text_transform(node: docutils.nodes.Element) -> None:
115
    """
116
    Apply extra text transformations to a document node and its children.
117
    
118
    Currently handles:
119
    - Converting \\url patterns to proper reference nodes
120
    - Recursively processing all child elements
121
    
122
    This function processes special text patterns that need to be converted
123
    to proper docutils nodes for correct rendering in different output formats.
124
    
125
    Parameters:
126
        node: Document element to process
127
        
128
    Side Effects:
129
        - Modifies node tree by replacing text nodes with reference nodes
130
        - Recursively processes all child elements
131
    """
132
```
133

134
## Usage Examples
135

136
### Custom Node Creation
137

138
```python
139
from sphinxcontrib.bibtex.nodes import bibliography, raw_latex
140

141
# Create a bibliography node (typically done by BibliographyDirective)
142
bib_node = bibliography("", docname="chapter1", ids=["bibliography-1"])
143

144
# Create a raw LaTeX node
145
latex_node = raw_latex("\\citep{smith2020}")
146
latex_node.rawsource = "\\citep{smith2020}"
147
```
148

149
### Transform Registration
150

151
The transform is automatically registered by the extension setup:
152

153
```python
154
# In sphinxcontrib.bibtex.__init__.setup()
155
app.add_post_transform(BibliographyTransform)
156
```
157

158
### LaTeX Node Handling
159

160
The LaTeX visitors are registered with specific writers:
161

162
```python
163
# In sphinxcontrib.bibtex.__init__.setup()
164
app.add_node(
165
    raw_latex, 
166
    latex=(visit_raw_latex, depart_raw_latex), 
167
    override=True
168
)
169
```
170

171
## Transform Processing Order
172

173
The bibliography transform runs at priority 5, which ensures it processes before:
174

175
1. **ReferencesResolver** (priority 10): Resolves cross-references and citations
176
2. **Other high-priority transforms**: Most other Sphinx transforms
177

178
This ordering is critical because:
179
- Bibliography nodes must be converted to citation nodes before cross-reference resolution
180
- Citation target nodes must exist when resolve_xref is called
181
- Backreferences can be properly established between citations and references
182

183
## Integration with Bibliography Processing
184

185
### Transform Workflow
186

187
1. **Parsing Phase**: 
188
   - BibliographyDirective creates bibliography nodes
189
   - CiteRole creates pending cross-reference nodes
190
   - All nodes are added to document tree
191

192
2. **Post-Transform Phase**:
193
   - BibliographyTransform runs (priority 5)
194
   - Bibliography nodes converted to citation lists
195
   - Text transformations applied to formatted entries
196

197
3. **Resolution Phase**:
198
   - ReferencesResolver runs (priority 10)  
199
   - Cross-references resolved using domain.resolve_xref
200
   - Final citation formatting applied
201

202
### Node Relationships
203

204
```
205
Document
206
├── pending_xref (from :cite: roles)
207
├── bibliography (from .. bibliography::)
208
│   └── [Replaced by citation list during transform]
209
└── Other content
210
```
211

212
After transform:
213

214
```
215
Document  
216
├── pending_xref (resolved to formatted citations)
217
├── citation_list (bullet_list, enumerated_list, or citations)
218
│   ├── citation (with formatted entry and backrefs)
219
│   └── citation (...)
220
└── Other content
221
```