0
# Extension Setup and Configuration
1

2
Sphinx AutoAPI extension setup, configuration management, and event handling for integrating with the Sphinx documentation system.
3

4
## Core Extension Setup
5

6
### Main Setup Function
7

8
```python { .api }
9
def setup(app):
10
    """
11
    Main Sphinx extension setup function that registers AutoAPI components.
12
    
13
    Args:
14
        app: Sphinx application instance to configure
15
        
16
    Returns:
17
        dict: Extension metadata with parallel read/write safe settings
18
        
19
    This function:
20
    - Registers custom configuration values
21
    - Adds custom directives and documenters  
22
    - Registers event handlers
23
    - Sets up template directories
24
    - Configures AutoAPI processing pipeline
25
    """
26
```
27

28
From `autoapi.extension`:
29
```python
30
import autoapi
31
```
32

33
## Configuration Options
34

35
AutoAPI provides extensive configuration through Sphinx config values registered during setup:
36

37
```python { .api }
38
# Required configuration
39
autoapi_dirs: list[str]
40
"""Required. Directories to scan for source code files."""
41

42
# Output control
43
autoapi_root: str = "autoapi"
44
"""Directory name for generated API documentation."""
45

46
autoapi_generate_api_docs: bool = True
47
"""Whether to generate API documentation files."""
48

49
autoapi_add_toctree_entry: bool = True
50
"""Whether to add AutoAPI entry to table of contents."""
51

52
autoapi_keep_files: bool = False
53
"""Whether to keep generated .rst files after build."""
54

55
# File discovery
56
autoapi_file_patterns: list[str] = ["*.py", "*.pyi"]
57
"""File patterns to include during source discovery."""
58

59
autoapi_ignore: list[str] = ["*migrations*"]
60
"""Patterns to ignore during source parsing."""
61

62
# Documentation options
63
autoapi_options: list[str] = [
64
    "members", "undoc-members", "private-members",
65
    "show-inheritance", "show-module-summary",
66
    "special-members", "imported-members"
67
]
68
"""Documentation generation options."""
69

70
autoapi_member_order: str = "bysource"
71
"""Member ordering: 'bysource', 'alphabetical', or 'groupwise'."""
72

73
autoapi_own_page_level: str = "module"
74
"""Level at which objects get their own page: 'module', 'class', 'function'."""
75

76
# Python-specific options
77
autoapi_python_class_content: str = "class"
78
"""Class docstring content: 'class', 'both', or 'init'."""
79

80
autoapi_python_use_implicit_namespaces: bool = False
81
"""Support for PEP 420 implicit namespace packages."""
82

83
# Template customization
84
autoapi_template_dir: str = None
85
"""Custom template directory for overriding default templates."""
86

87
autoapi_include_summaries: bool = None
88
"""Whether to include summary tables in generated docs."""
89

90
autoapi_prepare_jinja_env: callable = None
91
"""Custom function to prepare Jinja environment."""
92
```
93

94
## Event Handlers
95

96
AutoAPI registers several event handlers with Sphinx for processing integration:
97

98
### Core Processing Events
99

100
```python { .api }
101
def run_autoapi(app):
102
    """
103
    Core AutoAPI processing function triggered during Sphinx build.
104
    
105
    Args:
106
        app: Sphinx application instance
107
        
108
    This function:
109
    - Creates the Mapper instance
110
    - Loads and parses source files
111
    - Generates documentation objects
112
    - Outputs .rst files
113
    """
114
```
115

116
```python { .api }
117
def source_read(app, docname, source):
118
    """
119
    Event handler for source file reading to populate annotations.
120
    
121
    Args:
122
        app: Sphinx application instance
123
        docname (str): Name of the document being read
124
        source (list): List containing source content
125
        
126
    Populates type annotations from Sphinx environment data.
127
    """
128
```
129

130
### Build Events
131

132
```python { .api }
133
def build_finished(app, exception):
134
    """
135
    Event handler for build completion cleanup.
136
    
137
    Args:
138
        app: Sphinx application instance
139
        exception: Any exception that occurred during build
140
        
141
    Removes generated .rst files if autoapi_keep_files is False.
142
    """
143
```
144

145
```python { .api }
146
def doctree_read(app, doctree):
147
    """
148
    Event handler for injecting AutoAPI into table of contents.
149
    
150
    Args:
151
        app: Sphinx application instance
152
        doctree: Document tree being processed
153
        
154
    Dynamically adds AutoAPI documentation to TOC tree structure.
155
    """
156
```
157

158
### Viewcode Integration
159

160
```python { .api }
161
def viewcode_find(app, modname):
162
    """
163
    Event handler for viewcode extension integration.
164
    
165
    Args:
166
        app: Sphinx application instance
167
        modname (str): Module name being requested
168
        
169
    Returns:
170
        tuple: (source_code, locations_dict) or None if not found
171
        
172
    Provides source code locations for Sphinx viewcode extension.
173
    """
174
```
175

176
```python { .api }
177
def viewcode_follow_imported(app, modname, attribute):
178
    """
179
    Event handler for following imported references in viewcode.
180
    
181
    Args:
182
        app: Sphinx application instance
183
        modname (str): Module name containing the import
184
        attribute (str): Attribute name being followed
185
        
186
    Returns:
187
        str: Module name containing the actual definition, or None
188
        
189
    Resolves imported attribute references for viewcode links.
190
    """
191
```
192

193
## Custom Events
194

195
AutoAPI defines custom Sphinx events for extension:
196

197
```python { .api }
198
# Event: autoapi-skip-member
199
"""
200
Custom event fired to determine if a member should be skipped.
201

202
Parameters:
203
    app: Sphinx application instance
204
    what (str): Type of object ('module', 'class', 'method', etc.)
205
    name (str): Name of the member
206
    obj: AutoAPI object being processed
207
    skip (bool): Current skip status
208
    options (dict): AutoAPI options
209

210
Returns:
211
    bool: True to skip the member, False to include it
212
"""
213
```
214

215
## Constants and Defaults
216

217
```python { .api }
218
_DEFAULT_FILE_PATTERNS = ["*.py", "*.pyi"]
219
"""Default file patterns for source discovery."""
220

221
_DEFAULT_IGNORE_PATTERNS = ["*migrations*"]  
222
"""Default patterns to ignore during parsing."""
223

224
_DEFAULT_OPTIONS = [
225
    "members", "undoc-members", "private-members",
226
    "show-inheritance", "show-module-summary", 
227
    "special-members", "imported-members"
228
]
229
"""Default AutoAPI documentation options."""
230

231
_VALID_PAGE_LEVELS = ["module", "class", "function", "method"]
232
"""Valid values for autoapi_own_page_level configuration."""
233
```
234

235
## Integration Example
236

237
```python { .api }
238
# In Sphinx conf.py
239
extensions = ['autoapi.extension']
240

241
# Required: specify source directories
242
autoapi_dirs = ['src', 'my_package']
243

244
# Optional: customize behavior
245
autoapi_options = [
246
    'members',
247
    'undoc-members',
248
    'show-inheritance',
249
    'show-module-summary',
250
]
251

252
autoapi_root = 'api'
253
autoapi_file_patterns = ['*.py']
254
autoapi_ignore = ['*tests*', '*migrations*']
255
autoapi_python_class_content = 'both'
256
```
257

258
When Sphinx builds documentation, AutoAPI automatically discovers source files, parses them using static analysis, generates comprehensive API documentation, and integrates it into the documentation site.