0
# Custom Directives and Documenters
1

2
Sphinx directives and autodoc documenters that integrate AutoAPI's static analysis with Sphinx's documentation system. These provide enhanced autosummary capabilities, nested parsing, and comprehensive autodoc integration.
3

4
## AutoAPI Directives
5

6
### AutoapiSummary Directive
7

8
```python { .api }
9
class AutoapiSummary(Autosummary):
10
    """
11
    Enhanced autosummary directive using AutoAPI's static analysis.
12
    
13
    Extends Sphinx's standard autosummary directive to work with AutoAPI's
14
    statically analyzed objects instead of requiring imports. Generates
15
    summary tables with proper cross-references.
16
    
17
    Inherits from: sphinx.ext.autosummary.Autosummary
18
    """
19
    
20
    def get_items(self, names: list[str]):
21
        """
22
        Get summary items for the specified names using static analysis.
23
        
24
        Args:
25
            names (list[str]): Object names to summarize
26
            
27
        Returns:
28
            list[tuple]: List of (name, signature, summary, real_name) tuples
29
            
30
        Uses AutoAPI's parsed objects to generate summaries without
31
        requiring imports or code execution.
32
        """
33
```
34

35
### NestedParse Directive
36

37
```python { .api }
38
class NestedParse(Directive):
39
    """
40
    Directive for nested reStructuredText parsing with heading adjustment.
41
    
42
    Handles nested parsing of reStructuredText content while automatically
43
    removing or adjusting duplicate headings that would conflict with
44
    the containing document structure.
45
    
46
    Inherits from: docutils.parsers.rst.Directive
47
    """
48
    
49
    def run(self):
50
        """
51
        Execute the nested parsing with heading removal.
52
        
53
        Returns:
54
            list[Node]: Parsed document nodes with adjusted headings
55
            
56
        Processes nested reStructuredText content and removes the first
57
        heading to prevent title conflicts in generated documentation.
58
        """
59
```
60

61
### AutoapiInheritanceDiagram Directive
62

63
```python { .api }
64
class AutoapiInheritanceDiagram(sphinx.ext.inheritance_diagram.InheritanceDiagram):
65
    """
66
    Enhanced inheritance diagram directive using AutoAPI's static analysis.
67
    
68
    Extends Sphinx's standard inheritance_diagram directive to work with 
69
    AutoAPI's statically analyzed objects instead of requiring imports.
70
    Generates class inheritance diagrams using static analysis.
71
    
72
    Inherits from: sphinx.ext.inheritance_diagram.InheritanceDiagram
73
    """
74
    
75
    def run(self):
76
        """
77
        Generate inheritance diagram using static analysis.
78
        
79
        Returns:
80
            list[Node]: Inheritance diagram nodes
81
            
82
        Uses AutoAPI's static analysis to generate inheritance diagrams
83
        without requiring imports or code execution.
84
        """
85
```
86

87
From `autoapi.directives`:
88
```python
89
from autoapi.directives import AutoapiSummary, NestedParse
90
```
91

92
From `autoapi.inheritance_diagrams`:
93
```python
94
from autoapi.inheritance_diagrams import AutoapiInheritanceDiagram
95
```
96

97
## AutoAPI Documenters
98

99
AutoAPI provides a complete set of autodoc-compatible documenters that work with statically analyzed objects:
100

101
### Base Documenter
102

103
```python { .api }
104
class AutoapiDocumenter(Documenter):
105
    """
106
    Base documenter class for all AutoAPI objects.
107
    
108
    Provides common functionality for documenting statically analyzed
109
    objects without requiring imports. All specific documenters inherit
110
    from this base class.
111
    
112
    Inherits from: sphinx.ext.autodoc.Documenter
113
    """
114
    
115
    def get_attr(self, obj, name, *defargs):
116
        """
117
        Get attribute from AutoAPI object.
118
        
119
        Args:
120
            obj: AutoAPI object instance
121
            name (str): Attribute name to retrieve
122
            *defargs: Default values if attribute not found
123
            
124
        Returns:
125
            Any: Attribute value or default
126
            
127
        Retrieves attributes from AutoAPI objects using static analysis
128
        data instead of runtime introspection.
129
        """
130
    
131
    def import_object(self, raiseerror: bool = False):
132
        """
133
        Import/load the AutoAPI object for documentation.
134
        
135
        Args:
136
            raiseerror (bool): Whether to raise errors on import failure
137
            
138
        Returns:
139
            bool: True if object was successfully loaded
140
            
141
        Loads objects from AutoAPI's static analysis results rather
142
        than performing runtime imports.
143
        """
144
```
145

146
### Function Documenters
147

148
```python { .api }
149
class AutoapiFunctionDocumenter(AutoapiDocumenter):
150
    """
151
    Documenter for standalone functions.
152
    
153
    Handles documentation of module-level functions with complete
154
    signature information, parameter documentation, and return types
155
    extracted from static analysis.
156
    
157
    Supports:
158
    - Function signatures with type annotations
159
    - Parameter documentation from docstrings
160
    - Return type information
161
    - Decorator information
162
    - Overload handling
163
    """
164

165
class AutoapiMethodDocumenter(AutoapiDocumenter):
166
    """
167
    Documenter for class methods.
168
    
169
    Handles all types of class methods including instance methods,
170
    static methods, class methods, and special methods with proper
171
    inheritance and override detection.
172
    
173
    Supports:
174
    - Method type identification (static, class, instance)
175
    - Inheritance relationship documentation
176
    - Abstract method identification
177
    - Property method integration
178
    """
179
```
180

181
### Class Documenters
182

183
```python { .api }
184
class AutoapiClassDocumenter(AutoapiDocumenter):
185
    """
186
    Documenter for Python classes.
187
    
188
    Provides comprehensive class documentation including inheritance
189
    hierarchies, member organization, and constructor documentation
190
    with full static analysis integration.
191
    
192
    Supports:
193
    - Class inheritance documentation
194
    - Method Resolution Order (MRO)
195
    - Constructor parameter documentation
196
    - Member organization and filtering
197
    - Abstract class handling
198
    """
199

200
class AutoapiExceptionDocumenter(AutoapiDocumenter):
201
    """
202
    Documenter for exception classes.
203
    
204
    Specialized class documenter for exception classes with additional
205
    context for error handling and exception hierarchy documentation.
206
    
207
    Provides exception-specific templates and documentation patterns
208
    while maintaining full class documentation capabilities.
209
    """
210
```
211

212
### Property and Attribute Documenters
213

214
```python { .api }
215
class AutoapiPropertyDocumenter(AutoapiDocumenter):
216
    """
217
    Documenter for Python properties.
218
    
219
    Handles @property decorated methods with getter, setter, and
220
    deleter documentation, including type information and proper
221
    cross-referencing.
222
    
223
    Supports:
224
    - Property getter documentation
225
    - Setter and deleter methods
226
    - Type annotation integration
227
    - Read-only property identification
228
    """
229

230
class AutoapiAttributeDocumenter(AutoapiDocumenter):
231
    """
232
    Documenter for class and instance attributes.
233
    
234
    Documents class variables, instance attributes, and annotated
235
    attributes with type information and value documentation.
236
    
237
    Supports:
238
    - Class variable documentation
239
    - Instance attribute identification
240
    - Type annotation display
241
    - Default value representation
242
    """
243

244
class AutoapiDataDocumenter(AutoapiDocumenter):
245
    """
246
    Documenter for module-level data and constants.
247
    
248
    Handles module-level variables, constants, and configuration
249
    values with type annotations and value documentation.
250
    
251
    Supports:
252
    - Constant identification and documentation
253
    - Type annotation integration
254
    - Value representation for simple types
255
    - Import alias resolution
256
    """
257
```
258

259
### Decorator Documenter
260

261
```python { .api }
262
class AutoapiDecoratorDocumenter(AutoapiDocumenter):
263
    """
264
    Documenter for decorators and decorator factories.
265
    
266
    Provides specialized documentation for decorator functions with
267
    proper signature handling and usage examples.
268
    
269
    Supports:
270
    - Decorator signature documentation
271
    - Decorator factory parameter handling
272
    - Usage example integration
273
    - Cross-references to decorated objects
274
    """
275
```
276

277
### Module Documenter
278

279
```python { .api }
280
class AutoapiModuleDocumenter(AutoapiDocumenter):
281
    """
282
    Documenter for Python modules.
283
    
284
    Provides comprehensive module documentation with member summaries,
285
    import organization, and cross-package references.
286
    
287
    Supports:
288
    - Module-level docstring processing
289
    - Member summary generation
290
    - Import statement documentation
291
    - Submodule cross-references
292
    """
293
```
294

295
## Integration with Sphinx
296

297
### Documenter Registration
298

299
```python { .api }
300
# Documenters are registered with Sphinx during extension setup:
301
"""
302
app.add_autodocumenter(AutoapiModuleDocumenter)
303
app.add_autodocumenter(AutoapiClassDocumenter)
304
app.add_autodocumenter(AutoapiFunctionDocumenter)
305
app.add_autodocumenter(AutoapiMethodDocumenter)
306
app.add_autodocumenter(AutoapiPropertyDocumenter)
307
app.add_autodocumenter(AutoapiAttributeDocumenter)
308
app.add_autodocumenter(AutoapiDataDocumenter)
309
app.add_autodocumenter(AutoapiDecoratorDocumenter)
310
app.add_autodocumenter(AutoapiExceptionDocumenter)
311
"""
312
```
313

314
### Directive Registration
315

316
```python { .api }
317
# Directives are registered during extension setup:
318
"""
319
app.add_directive('autoapi-nested-parse', NestedParse)
320
app.add_directive('autoapisummary', AutoapiSummary)
321
"""
322
```
323

324
## Advanced Features
325

326
### Static Analysis Integration
327

328
```python { .api }
329
# Documenters leverage AutoAPI's static analysis:
330
"""
331
- No runtime imports required
332
- Safe documentation of broken/incomplete code
333
- Type annotation preservation
334
- Cross-reference resolution without execution
335
- Inheritance analysis without class instantiation
336
"""
337
```
338

339
### Template Integration
340

341
```python { .api }
342
# Documenters work with AutoAPI templates:
343
"""
344
- Object-specific template selection
345
- Context data from static analysis
346
- Custom template support
347
- Jinja2 filter integration
348
- reStructuredText generation
349
"""
350
```
351

352
## Usage Examples
353

354
### AutoapiSummary Usage
355

356
```rst
357
.. autoapisummary::
358
   :toctree: _autosummary
359

360
   mymodule.MyClass
361
   mymodule.my_function
362
   mymodule.CONSTANT
363
```
364

365
### NestedParse Usage
366

367
```rst
368
.. autoapi-nested-parse::
369
   
370
   This content will be parsed with heading adjustment.
371
   
372
   Title That Would Conflict
373
   =========================
374
   
375
   This title will be removed or adjusted.
376
```
377

378
### Documenter Integration
379

380
```python { .api }
381
# Documenters integrate seamlessly with autodoc:
382
"""
383
.. autoclass:: mymodule.MyClass
384
   :members:
385
   :show-inheritance:
386

387
.. autofunction:: mymodule.my_function
388

389
.. autodata:: mymodule.CONSTANT
390
"""
391
```
392

393
The directive and documenter system provides seamless integration between AutoAPI's static analysis capabilities and Sphinx's documentation generation, enabling comprehensive API documentation without the risks and requirements of runtime code execution.