0
# Rendering and Template Functions
1

2
Template functions and utilities for formatting code signatures, handling cross-references, organizing documentation output, and controlling the presentation of Python API documentation.
3

4
**Note**: Most rendering functions are Jinja2 template filters that receive a `context` parameter automatically. The signatures below show the user-visible parameters only.
5

6
## Capabilities
7

8
### Code Formatting Functions
9

10
Functions for formatting Python code signatures and snippets with appropriate line length and style.
11

12
```python { .api }
13
def do_format_code(code: str, line_length: int = 88) -> str:
14
    """
15
    Format code snippets with appropriate line wrapping.
16
    
17
    Parameters:
18
    - code: str - The code to format
19
    - line_length: int - Maximum line length (default: 88)
20
    
21
    Returns:
22
    str - Formatted code with proper line breaks
23
    """
24

25
def do_format_signature(
26
    callable_path: str,
27
    function: object,
28
    line_length: int,
29
    *,
30
    annotations: bool | None = None,
31
    crossrefs: bool = False
32
) -> str:
33
    """
34
    Format function/method signatures for display.
35
    
36
    Parameters:
37
    - callable_path: str - Path to the callable object
38
    - function: object - Function object to format
39
    - line_length: int - Maximum line length
40
    - annotations: bool | None - Whether to show type annotations (optional)
41
    - crossrefs: bool - Whether to generate cross-references (default: False)
42
    
43
    Returns:
44
    str - Formatted signature with proper line breaks
45
    """
46

47
def do_format_attribute(
48
    attribute_path: str,
49
    attribute: object,
50
    line_length: int,
51
    *,
52
    crossrefs: bool = False,
53
    show_value: bool = True
54
) -> str:
55
    """
56
    Format attribute signatures for display.
57
    
58
    Parameters:
59
    - attribute_path: str - Path to the attribute object  
60
    - attribute: object - Attribute object to format
61
    - line_length: int - Maximum line length
62
    - crossrefs: bool - Whether to generate cross-references (default: False)
63
    - show_value: bool - Whether to show the attribute value (default: True)
64
    
65
    Returns:
66
    str - Formatted attribute signature
67
    """
68

69
def do_format_type_alias(
70
    type_alias: str,
71
    line_length: int = 60
72
) -> str:
73
    """
74
    Format type alias definitions for display.
75
    
76
    Parameters:
77
    - type_alias: str - The type alias to format
78
    - line_length: int - Maximum line length (default: 60)
79
    
80
    Returns:
81
    str - Formatted type alias definition
82
    """
83
```
84

85
**Usage Example:**
86

87
```python
88
# In a Jinja2 template
89
{{ signature | do_format_signature(80) }}
90
{{ code_block | do_format_code(100) }}
91
```
92

93
### Cross-Reference Functions
94

95
Functions for generating and managing cross-references between documentation objects.
96

97
```python { .api }
98
def do_crossref(path: str, *, brief: bool = True) -> Markup:
99
    """
100
    Generate cross-references to documentation objects.
101
    
102
    Parameters:
103
    - path: str - Dotted path to the target object
104
    - brief: bool - Whether to use brief reference format (default: True)
105
    
106
    Returns:
107
    str - HTML markup for the cross-reference
108
    """
109

110
def do_multi_crossref(text: str, *, code: bool = True) -> str:
111
    """
112
    Handle multiple cross-references in text content.
113
    
114
    Parameters:
115
    - text: str - Text containing cross-reference patterns
116
    - code: bool - Whether to wrap references in code tags (default: True)
117
    
118
    Returns:
119
    str - Text with cross-references converted to HTML links
120
    """
121

122
def do_stash_crossref(
123
    path: str,
124
    identifier: str
125
) -> str:
126
    """
127
    Stash cross-references for later processing.
128
    
129
    Parameters:
130
    - path: str - Path to the referenced object
131
    - identifier: str - Unique identifier for the reference
132
    
133
    Returns:
134
    str - Stashed reference placeholder
135
    """
136

137
def do_split_path(
138
    path: str,
139
    full_path: str
140
) -> list[tuple[str, str, str, str]]:
141
    """
142
    Split object paths for navigation and display.
143
    
144
    Parameters:
145
    - path: str - Object path to split
146
    - full_path: str - Full path context
147
    
148
    Returns:
149
    list[tuple[str, str, str, str]] - Split path components
150
    """
151
```
152

153
**Usage Example:**
154

155
```python
156
# In Python code or templates
157
crossref_html = do_crossref("numpy.array", brief=False)
158
processed_text = do_multi_crossref("See `numpy.array` and `pandas.DataFrame`")
159
```
160

161
### Object Organization Functions
162

163
Functions for filtering, ordering, and organizing documentation objects.
164

165
```python { .api }
166
def do_filter_objects(
167
    objects_dictionary: dict[str, object],
168
    *,
169
    filters: Sequence[tuple[Pattern, bool]] | Literal["public"] | None = None,
170
    members_list: bool | list[str] | None = None,
171
    inherited_members: bool | list[str] = False,
172
    keep_no_docstrings: bool = True
173
) -> list[object]:
174
    """
175
    Filter objects based on inclusion/exclusion patterns.
176
    
177
    Parameters:
178
    - objects_dictionary: dict[str, object] - Dictionary of objects to filter
179
    - filters: Filter patterns (compiled regex patterns) or "public" literal
180
    - members_list: Specific members to include or boolean for all
181
    - inherited_members: Whether to include inherited members  
182
    - keep_no_docstrings: Whether to keep objects without docstrings
183
    
184
    Returns:
185
    list[object] - Filtered list of objects
186
    """
187

188
def do_order_members(
189
    members: list,
190
    order: Order
191
) -> list:
192
    """
193
    Order object members according to specified criteria.
194
    
195
    Parameters:
196
    - members: list - List of member objects to order
197
    - order: Order - Ordering method ("alphabetical", "source", "__all__")
198
    
199
    Returns:
200
    list - Ordered list of members
201
    """
202
```
203

204
**Usage Example:**
205

206
```python
207
# Filter private members
208
filtered = do_filter_objects(all_members, ["!^_[^_]"])
209

210
# Order alphabetically
211
ordered = do_order_members(members, "alphabetical")
212
```
213

214
### Section Rendering Functions
215

216
Functions for rendering different types of objects as documentation sections.
217

218
```python { .api }
219
def do_as_attributes_section(
220
    attributes: list,
221
    **kwargs
222
) -> str:
223
    """
224
    Render attributes as a documentation section.
225
    
226
    Parameters:
227
    - attributes: list - List of attribute objects
228
    - **kwargs: Additional rendering options
229
    
230
    Returns:
231
    str - Rendered HTML section
232
    """
233

234
def do_as_functions_section(
235
    functions: list,
236
    **kwargs
237
) -> str:
238
    """
239
    Render functions as a documentation section.
240
    
241
    Parameters:
242
    - functions: list - List of function objects
243
    - **kwargs: Additional rendering options
244
    
245
    Returns:
246
    str - Rendered HTML section
247
    """
248

249
def do_as_classes_section(
250
    classes: list,
251
    **kwargs
252
) -> str:
253
    """
254
    Render classes as a documentation section.
255
    
256
    Parameters:
257
    - classes: list - List of class objects
258
    - **kwargs: Additional rendering options
259
    
260
    Returns:
261
    str - Rendered HTML section
262
    """
263

264
def do_as_modules_section(
265
    modules: list,
266
    **kwargs
267
) -> str:
268
    """
269
    Render modules as a documentation section.
270
    
271
    Parameters:
272
    - modules: list - List of module objects
273
    - **kwargs: Additional rendering options
274
    
275
    Returns:
276
    str - Rendered HTML section
277
    """
278

279
def do_as_type_aliases_section(
280
    type_aliases: list,
281
    **kwargs
282
) -> str:
283
    """
284
    Render type aliases as a documentation section.
285
    
286
    Parameters:
287
    - type_aliases: list - List of type alias objects
288
    - **kwargs: Additional rendering options
289
    
290
    Returns:
291
    str - Rendered HTML section
292
    """
293
```
294

295
### Template and Navigation Functions
296

297
Functions for template management and navigation structure generation.
298

299
```python { .api }
300
def do_get_template(
301
    env: object,
302
    obj: str | object
303
) -> str:
304
    """
305
    Get appropriate Jinja2 template for rendering objects.
306
    
307
    Parameters:
308
    - env: object - Jinja2 environment
309
    - obj: str | object - Object or template name
310
    
311
    Returns:
312
    str - Template name for the object
313
    """
314

315
def do_backlink_tree(
316
    backlinks: list
317
) -> Tree:
318
    """
319
    Create a tree structure of backlinks for navigation.
320
    
321
    Parameters:
322
    - backlinks: list - List of backlink objects
323
    
324
    Returns:
325
    Tree - Tree structure for navigation
326
    """
327
```
328

329
### AutorefsHook Class
330

331
Hook class for automatic reference generation and integration with mkdocs-autorefs.
332

333
```python { .api }
334
class AutorefsHook:
335
    """Hook class for automatic reference generation."""
336
    
337
    def __init__(
338
        self,
339
        current_object: object,
340
        config: dict[str, Any]
341
    ) -> None:
342
        """
343
        Initialize the AutorefsHook.
344
        
345
        Parameters:
346
        - current_object: object - Current object being processed
347
        - config: dict[str, Any] - Handler configuration
348
        """
349
        
350
    def expand_identifier(self, identifier: str) -> str:
351
        """
352
        Expand short identifiers to full dotted paths.
353
        
354
        Parameters:
355
        - identifier: str - Short identifier to expand
356
        
357
        Returns:
358
        str - Expanded dotted path
359
        """
360
        
361
    def get_context(self) -> object:
362
        """
363
        Get the current context for cross-reference resolution.
364
        
365
        Returns:
366
        object - Context object for autorefs
367
        """
368
```
369

370
**Usage Example:**
371

372
```python
373
from mkdocstrings_handlers.python import AutorefsHook
374

375
# Create hook instance
376
hook = AutorefsHook()
377

378
# Use in mkdocstrings configuration
379
hook.on_config({"base_url": "https://example.com/docs/"})
380
```
381

382
## Types
383

384
```python { .api }
385
Order = Literal["__all__", "alphabetical", "source"]
386
"""
387
Ordering methods for organizing object members:
388
- __all__: Order according to __all__ module attribute
389
- alphabetical: Order alphabetically by name  
390
- source: Order by appearance in source code
391
"""
392

393
Tree = dict[str, Any]
394
"""Tree data structure for organizing hierarchical documentation."""
395
```