0
# Configuration
1
2
Sphinx configuration values that control the behavior of sphinx-automodapi directives. These settings are added to your Sphinx `conf.py` file to customize how the extension generates documentation.
3
4
## Capabilities
5
6
### automodapi Configuration
7
8
Settings that control the behavior of the `automodapi` directive and its document generation process.
9
10
```python { .api }
11
# conf.py settings
12
automodapi_inheritance_diagram: bool = True
13
automodapi_toctreedirnm: str = 'api'
14
automodapi_writereprocessed: bool = False
15
```
16
17
#### automodapi_inheritance_diagram
18
19
Controls whether inheritance diagrams are generated by default for classes in automodapi documentation.
20
21
**Type**: `bool`
22
**Default**: `True`
23
**Usage**: Can be overridden per-directive with `:inheritance-diagram:` or `:no-inheritance-diagram:` options
24
25
```python
26
# In conf.py
27
automodapi_inheritance_diagram = False # Disable diagrams globally
28
```
29
30
#### automodapi_toctreedirnm
31
32
Specifies the directory name used for API documentation in the toctree structure.
33
34
**Type**: `str`
35
**Default**: `'api'`
36
**Usage**: Controls where generated API files are organized in the documentation structure
37
38
```python
39
# In conf.py
40
automodapi_toctreedirnm = 'reference' # Use 'reference' instead of 'api'
41
```
42
43
#### automodapi_writereprocessed
44
45
Controls whether reprocessed files are written to disk during documentation generation.
46
47
**Type**: `bool`
48
**Default**: `False`
49
**Usage**: Primarily for debugging and development of the extension itself
50
51
```python
52
# In conf.py
53
automodapi_writereprocessed = True # Enable for debugging
54
```
55
56
### automodsumm Configuration
57
58
Settings that control the behavior of `automodsumm` and `automod-diagram` directives.
59
60
```python { .api }
61
# conf.py settings
62
automodsumm_writereprocessed: bool = False
63
automodsumm_inherited_members: bool = False
64
automodsumm_included_members: list[str] = ['__init__', '__call__']
65
automodsumm_properties_are_attributes: bool = True
66
```
67
68
#### automodsumm_writereprocessed
69
70
Controls whether reprocessed autosummary files are written to disk.
71
72
**Type**: `bool`
73
**Default**: `False`
74
**Usage**: For debugging autosummary generation process
75
76
```python
77
# In conf.py
78
automodsumm_writereprocessed = True
79
```
80
81
#### automodsumm_inherited_members
82
83
Global setting for whether to include inherited class members in documentation.
84
85
**Type**: `bool`
86
**Default**: `False`
87
**Usage**: Can be overridden per-directive with `:inherited-members:` or `:no-inherited-members:` options
88
89
```python
90
# In conf.py
91
automodsumm_inherited_members = True # Include inherited members globally
92
```
93
94
#### automodsumm_included_members
95
96
List of special method names to include in documentation even if they would normally be filtered out.
97
98
**Type**: `list[str]`
99
**Default**: `['__init__', '__call__']`
100
**Usage**: Controls which dunder methods appear in generated documentation
101
102
```python
103
# In conf.py
104
automodsumm_included_members = ['__init__', '__call__', '__enter__', '__exit__']
105
```
106
107
#### automodsumm_properties_are_attributes
108
109
Controls whether class properties are treated as attributes in the documentation.
110
111
**Type**: `bool`
112
**Default**: `True`
113
**Usage**: Affects how properties are categorized and displayed
114
115
```python
116
# In conf.py
117
automodsumm_properties_are_attributes = False # Treat properties separately
118
```
119
120
## Configuration Setup
121
122
These configuration values are automatically registered when the extension is loaded. Add them to your `conf.py` file:
123
124
```python { .api }
125
def setup(app: Sphinx) -> dict[str, bool]:
126
"""
127
Register configuration values with Sphinx.
128
129
Each configuration value is registered with:
130
- Default value
131
- Rebuild requirement ('env' for environment, True for full rebuild)
132
"""
133
```
134
135
### Complete Example Configuration
136
137
```python
138
# conf.py
139
extensions = [
140
'sphinx_automodapi.automodapi',
141
'sphinx_automodapi.smart_resolver',
142
]
143
144
# automodapi settings
145
automodapi_inheritance_diagram = True
146
automodapi_toctreedirnm = 'api'
147
automodapi_writereprocessed = False
148
149
# automodsumm settings
150
automodsumm_writereprocessed = False
151
automodsumm_inherited_members = False
152
automodsumm_included_members = ['__init__', '__call__']
153
automodsumm_properties_are_attributes = True
154
```
155
156
## Configuration Value Types
157
158
```python { .api }
159
# Type definitions for configuration values
160
ConfigValue = Union[bool, str, list[str]]
161
162
# Rebuild requirement types
163
RebuildRequirement = Union[bool, str] # True, False, 'env', or 'html'
164
```
165
166
## Advanced Configuration
167
168
### Extension Dependencies
169
170
sphinx-automodapi automatically sets up required extensions:
171
172
```python
173
# Automatically loaded extensions
174
'sphinx.ext.autosummary' # For summary table generation
175
'sphinx.ext.inheritance_diagram' # For class diagrams
176
```
177
178
### Template Customization
179
180
The extension includes custom templates that can be overridden:
181
182
- `autosummary_core/base.rst`: Base template for autosummary
183
- `autosummary_core/class.rst`: Template for class documentation
184
- `autosummary_core/module.rst`: Template for module documentation
185
186
To customize templates, create corresponding files in your documentation's `_templates/autosummary_core/` directory.
187
188
### Integration Notes
189
190
Configuration values affect different aspects of the documentation generation:
191
192
1. **Build-time settings**: Control how files are processed and generated
193
2. **Runtime settings**: Affect directive behavior during document parsing
194
3. **Output settings**: Control the format and organization of generated content
195
196
The configuration system integrates with Sphinx's standard configuration mechanism, ensuring that settings are properly validated and available throughout the documentation build process.