0
# Jinja Domain
1

2
Specialized Sphinx domain for documenting Jinja2 templates, filters, tests, and node classes. Automatically generates comprehensive API documentation from Jinja mappings and class hierarchies with proper signatures and cross-references.
3

4
## Capabilities
5

6
### Domain Registration
7

8
The Jinja domain is automatically registered when the extension loads and Jinja is available.
9

10
```python { .api }
11
def setup(app):
12
    """
13
    Register Jinja domain if Jinja is installed.
14
    
15
    Conditionally loads the Jinja domain functionality only when the
16
    Jinja2 library is available in the environment.
17
    
18
    Parameters:
19
    - app: Sphinx application instance
20
    """
21
```
22

23
### Filter Documentation
24

25
Directive for generating documentation from Jinja filter mappings.
26

27
```python { .api }
28
# RST directive usage:
29
# .. jinja:filters:: jinja2.filters.FILTERS
30
#
31
# Automatically generates documentation for all filters in the mapping
32
```
33

34
### Test Documentation
35

36
Directive for generating documentation from Jinja test mappings.
37

38
```python { .api }
39
# RST directive usage:
40
# .. jinja:tests:: jinja2.tests.TESTS
41
#
42
# Automatically generates documentation for all tests in the mapping
43
```
44

45
### Node Documentation
46

47
Directive for generating documentation from Jinja Node class hierarchies.
48

49
```python { .api }
50
# RST directive usage:
51
# .. jinja:nodes:: jinja2.nodes.Node
52
#
53
# Recursively documents Node class and all subclasses
54
```
55

56
## Domain Classes
57

58
### MappedFunctionsDirective
59

60
Sphinx directive that processes Jinja function mappings (filters/tests) and generates documentation.
61

62
```python { .api }
63
class MappedFunctionsDirective(SphinxDirective):
64
    """
65
    Generate documentation from Jinja function mappings.
66
    
67
    Takes a dictionary mapping names to functions and produces rendered
68
    documentation with signatures, descriptions, and aliases. Used for
69
    both filters and tests directives.
70
    
71
    Attributes:
72
    - required_arguments: 1 (import path to mapping dict)
73
    """
74
    
75
    def _build_functions(self):
76
        """
77
        Import mapping and build function documentation.
78
        
79
        Processes the function mapping to identify aliases, extract
80
        signatures and docstrings, and prepare documentation content.
81
        
82
        Returns:
83
        list: Rendered Sphinx nodes for function documentation
84
        """
85
        
86
    def _build_table(self):
87
        """
88
        Build table of contents for documented functions.
89
        
90
        Creates a 5-column CSV table with function names as cross-references,
91
        organized alphabetically in columns for easy navigation.
92
        
93
        Returns:
94
        list: Rendered Sphinx nodes for the table
95
        """
96
        
97
    def run(self):
98
        """
99
        Execute directive processing.
100
        
101
        Builds both the function documentation and table of contents,
102
        returning the table above the detailed documentation.
103
        
104
        Returns:
105
        list: Complete list of rendered Sphinx nodes
106
        """
107
```
108

109
### NodesDirective
110

111
Sphinx directive that documents Jinja Node class hierarchies recursively.
112

113
```python { .api }
114
class NodesDirective(SphinxDirective):
115
    """
116
    Generate documentation for Jinja Node class hierarchies.
117
    
118
    Takes a base Node class and recursively documents it and all
119
    subclasses in depth-first order with parent references.
120
    
121
    Attributes:
122
    - required_arguments: 1 (import path to base Node class)
123
    """
124
    
125
    def run(self):
126
        """
127
        Execute directive processing.
128
        
129
        Recursively walks the Node class hierarchy and generates
130
        autodoc-style documentation for each class.
131
        
132
        Returns:
133
        list: Rendered Sphinx nodes for all Node classes
134
        """
135
```
136

137
### Jinja Domain Class
138

139
```python { .api }
140
class JinjaDomain(Domain):
141
    """
142
    Sphinx domain for Jinja documentation.
143
    
144
    Provides jinja:filters, jinja:tests, and jinja:nodes directives
145
    for comprehensive Jinja2 API documentation.
146
    
147
    Attributes:
148
    - name: "jinja"
149
    - label: "Jinja"
150
    - directives: {
151
        "filters": MappedFunctionsDirective,
152
        "tests": MappedFunctionsDirective, 
153
        "nodes": NodesDirective
154
      }
155
    """
156
```
157

158
### JinjaStyle (Pygments)
159

160
Custom Pygments syntax highlighting style for Jinja themes.
161

162
```python { .api }
163
class JinjaStyle(Style):
164
    """
165
    Custom Pygments style for Jinja documentation.
166
    
167
    Provides syntax highlighting colors optimized for Jinja templates
168
    and Python code in Jinja-themed documentation.
169
    
170
    Attributes:
171
    - background_color: "#f8f8f8"
172
    - default_style: ""
173
    - styles: dict mapping token types to style strings
174
    """
175
```
176

177
## Function Documentation Builder
178

179
### build_function_directive
180

181
Core function that generates reStructuredText documentation for Jinja functions.
182

183
```python { .api }
184
def build_function_directive(name, aliases, func):
185
    """
186
    Build function directive with signature and documentation.
187
    
188
    Extracts function signature, docstring, and handles special cases
189
    for Jinja filters (removing internal arguments, unwrapping async variants).
190
    
191
    Parameters:
192
    - name: Primary name for the function
193
    - aliases: List of alternative names for the function
194
    - func: The function object to document
195
    
196
    Returns:
197
    list: Lines of reStructuredText for the function directive
198
    """
199
```
200

201
## Usage Examples
202

203
### Document Jinja Filters
204

205
Generate comprehensive filter documentation:
206

207
```rst
208
.. jinja:filters:: jinja2.filters.FILTERS
209

210
This creates documentation for all built-in Jinja filters including:
211
- Function signatures with proper parameter handling
212
- Complete docstrings
213
- Alias information (e.g., `e` as alias for `escape`)
214
- Alphabetical table of contents
215
```
216

217
### Document Jinja Tests
218

219
Generate test function documentation:
220

221
```rst
222
.. jinja:tests:: jinja2.tests.TESTS
223

224
This creates documentation for all built-in Jinja tests including:
225
- Boolean test functions (divisibleby, even, odd, etc.)
226
- String tests (lower, upper, etc.)
227
- Container tests (iterable, mapping, etc.)
228
- Proper signature extraction and alias handling
229
```
230

231
### Document Node Classes
232

233
Generate Node class hierarchy documentation:
234

235
```rst
236
.. jinja:nodes:: jinja2.nodes.Node
237

238
This recursively documents:
239
- Base Node class with common attributes
240
- All subclasses (Expr, Stmt, Template, etc.)
241
- Abstract methods for abstract classes
242
- Parent class references
243
- Class inheritance relationships
244
```
245

246
### Custom Filter Documentation
247

248
Document your own filter mappings:
249

250
```rst
251
.. jinja:filters:: mypackage.filters.CUSTOM_FILTERS
252

253
Where mypackage.filters.py contains:
254

255
.. code-block:: python
256

257
   def my_filter(value, arg1, arg2="default"):
258
       """Custom filter that processes values."""
259
       return f"{value}-{arg1}-{arg2}"
260
   
261
   CUSTOM_FILTERS = {
262
       'my_filter': my_filter,
263
       'custom': my_filter,  # alias
264
   }
265
```
266

267
### Custom Test Documentation
268

269
Document custom test functions:
270

271
```rst
272
.. jinja:tests:: mypackage.tests.CUSTOM_TESTS
273

274
Where mypackage.tests.py contains:
275

276
.. code-block:: python
277

278
   def is_valid_email(value):
279
       """Test if value is a valid email address."""
280
       import re
281
       pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
282
       return re.match(pattern, value) is not None
283
   
284
   CUSTOM_TESTS = {
285
       'valid_email': is_valid_email,
286
       'email': is_valid_email,  # alias
287
   }
288
```
289

290
## Special Features
291

292
### Async Filter Handling
293

294
The domain automatically handles Jinja async filter variants:
295

296
```python
297
# Async filters are unwrapped to their sync variants for documentation
298
@jinja_async_variant
299
def async_my_filter(value):
300
    # This will be unwrapped to the sync version for signature extraction
301
    pass
302
```
303

304
### Context Filter Handling
305

306
Filters that receive context are handled specially:
307

308
```python
309
# Context/environment filters have their first argument removed from docs
310
@jinja_pass_environment  
311
def env_filter(environment, value, arg):
312
    # Documented signature will be: env_filter(value, arg)
313
    pass
314
```
315

316
### Comparison Operator Preference
317

318
Comparison operators get special handling in alias selection:
319

320
```python
321
# Short comparison names are preferred as primary names
322
TESTS = {
323
    'eq': operator.eq,
324
    'equalto': operator.eq,  # 'eq' becomes primary, 'equalto' is alias
325
}
326
```