0
# Core Directives
1

2
The main documentation generation directives that automatically discover module contents and generate comprehensive documentation. These directives form the core functionality of sphinx-automodapi.
3

4
## Capabilities
5

6
### automodapi Directive
7

8
Generates complete API documentation for a module including the module docstring, summary tables of functions and classes, detailed documentation for each member, and optional inheritance diagrams.
9

10
```rst { .api }
11
.. automodapi:: module.name
12
   :include-all-objects:
13
   :inheritance-diagram:
14
   :no-inheritance-diagram:
15
   :skip: obj1, obj2
16
   :include: obj1, obj2
17
   :no-main-docstr:
18
   :headings: -^
19
   :no-heading:
20
   :sort:
21
```
22

23
**Parameters:**
24
- `module.name`: The fully qualified name of the module to document
25
- `:include-all-objects:`: Include variables and other objects, not just functions and classes
26
- `:inheritance-diagram:` / `:no-inheritance-diagram:`: Control inheritance diagram display
27
- `:skip: obj1, obj2`: Skip specified objects from documentation
28
- `:include: obj1, obj2`: Include only specified objects in documentation
29
- `:no-main-docstr:`: Skip the module's main docstring
30
- `:headings: str`: Characters to use for section headings (default: "-^")
31
- `:no-heading:`: Don't create a top-level heading for the module
32
- `:sort:`: Sort objects alphabetically
33

34
#### Usage Example
35

36
```rst
37
Basic usage:
38

39
.. automodapi:: mypackage.utils
40

41
With options:
42

43
.. automodapi:: mypackage.core
44
   :include-all-objects:
45
   :skip: internal_helper
46
   :sort:
47
```
48

49
### automodsumm Directive
50

51
Generates autosummary-style tables for module contents with automatic discovery and flexible filtering options. Unlike Sphinx's built-in autosummary, this doesn't require manually listing each item.
52

53
```rst { .api }
54
.. automodsumm:: module.name
55
   :classes-only:
56
   :functions-only:
57
   :variables-only:
58
   :skip: obj1, obj2
59
   :allowed-package-names: pkg1, pkg2
60
   :inherited-members:
61
   :no-inherited-members:
62
   :sort:
63
```
64

65
**Parameters:**
66
- `module.name`: The fully qualified name of the module to summarize
67
- `:classes-only:`: Include only classes in the summary table
68
- `:functions-only:`: Include only functions in the summary table
69
- `:variables-only:`: Include only variables in the summary table
70
- `:skip: obj1, obj2`: Skip specified objects from the summary
71
- `:allowed-package-names: pkg1, pkg2`: Limit objects to specified packages
72
- `:inherited-members:` / `:no-inherited-members:`: Control inherited member inclusion
73
- `:sort:`: Sort objects alphabetically
74

75
Note: The filtering options `:classes-only:`, `:functions-only:`, and `:variables-only:` are mutually exclusive.
76

77
#### Usage Example
78

79
```rst
80
Basic summary:
81

82
.. automodsumm:: mypackage.models
83

84
Functions only:
85

86
.. automodsumm:: mypackage.helpers
87
   :functions-only:
88
   :skip: _internal_helper
89
   :sort:
90
```
91

92
### automod-diagram Directive
93

94
Generates inheritance diagrams for classes found in a module using Graphviz. This directive extends Sphinx's inheritance_diagram functionality with automatic class discovery.
95

96
```rst { .api }
97
.. automod-diagram:: module.name
98
```
99

100
**Parameters:**
101
- `module.name`: The fully qualified name of the module containing classes to diagram
102

103
This directive inherits all options from `sphinx.ext.inheritance_diagram.InheritanceDiagram`, including:
104
- `:parts: N`: Show only the last N parts of class names
105
- `:private-bases:`: Include private base classes
106
- `:caption: text`: Add a caption to the diagram
107

108
#### Usage Example
109

110
```rst
111
Basic inheritance diagram:
112

113
.. automod-diagram:: mypackage.models
114

115
With options:
116

117
.. automod-diagram:: mypackage.widgets
118
   :parts: 2
119
   :caption: Widget class hierarchy
120
```
121

122
## Directive Implementation Details
123

124
### Class Hierarchy
125

126
```python { .api }
127
# Base classes for the directives
128
from sphinx.ext.autosummary import Autosummary
129
from sphinx.ext.inheritance_diagram import InheritanceDiagram
130

131
class Automodsumm(Autosummary):
132
    """Implements the automodsumm directive"""
133
    
134
class Automoddiagram(InheritanceDiagram):
135
    """Implements the automod-diagram directive"""
136
```
137

138
### Processing Functions
139

140
```python { .api }
141
def process_automodapi(app: Sphinx, docname: str, source: list[str]) -> None:
142
    """
143
    Sphinx event handler that processes automodapi directives in source files.
144
    
145
    Parameters:
146
    - app: Sphinx application instance
147
    - docname: Name of the document being processed
148
    - source: List containing the source content (modified in-place)
149
    """
150

151
def process_automodsumm_generation(app: Sphinx) -> None:
152
    """
153
    Sphinx event handler that processes automodsumm directive generation.
154
    
155
    Parameters:
156
    - app: Sphinx application instance
157
    """
158

159
def automodapi_replace(sourcestr: str, app: Sphinx, dotoctree: bool = True, 
160
                      docname: str = None, warnings: bool = True) -> str:
161
    """
162
    Replace automodapi directives in source string with generated documentation.
163
    
164
    Parameters:
165
    - sourcestr: Source string containing automodapi directives
166
    - app: Sphinx application instance
167
    - dotoctree: Whether to include toctree directives
168
    - docname: Name of the current document
169
    - warnings: Whether to issue warnings for problems
170
    
171
    Returns:
172
    - str: Source string with automodapi directives replaced
173
    """
174
```
175

176
## Integration with Sphinx
177

178
These directives integrate with Sphinx through the extension setup system:
179

180
```python { .api }
181
def setup(app: Sphinx) -> dict[str, bool]:
182
    """
183
    Set up the directives extension with Sphinx.
184
    
185
    Registers:
186
    - automod-diagram directive  
187
    - automodsumm directive
188
    - Event handlers for processing (source-read, builder-inited)
189
    - Configuration values
190
    
191
    Returns:
192
    - dict: Parallel processing compatibility flags
193
    
194
    Extensions loaded:
195
    - sphinx.ext.autosummary (for summary table generation)
196
    - sphinx.ext.inheritance_diagram (for class diagrams)  
197
    - sphinx_automodapi.autodoc_enhancements (for enhanced attribute access)
198
    """
199
```