0
# Sphinx AutoAPI
1

2
A Sphinx extension for automatically generating complete API documentation from source code without requiring the project to be loaded, run, or imported. Unlike traditional Sphinx autodoc which requires manual authoring and uses code imports, AutoAPI finds and generates documentation by parsing source code using static analysis.
3

4
## Package Information
5

6
- **Package Name**: sphinx-autoapi
7
- **Language**: Python
8
- **Installation**: `pip install sphinx-autoapi`
9
- **Minimum Python Version**: 3.9
10
- **Dependencies**: astroid, Jinja2, PyYAML, sphinx>=7.4.0
11

12
## Core Imports
13

14
```python
15
import autoapi
16
```
17

18
For Sphinx configuration:
19

20
```python
21
# In conf.py
22
extensions.append('autoapi.extension')
23
```
24

25
## Basic Usage
26

27
```python
28
# Add to Sphinx conf.py
29
extensions = ['autoapi.extension']
30

31
# Configure AutoAPI to scan your source code directories
32
autoapi_dirs = ['path/to/source/files', 'src']
33

34
# Optional: customize behavior
35
autoapi_options = [
36
    'members',
37
    'undoc-members', 
38
    'private-members',
39
    'show-inheritance',
40
    'show-module-summary',
41
    'special-members',
42
    'imported-members',
43
]
44

45
# Optional: customize output location (default: 'autoapi')
46
autoapi_root = 'api'
47

48
# Optional: customize file patterns to include
49
autoapi_file_patterns = ['*.py', '*.pyi']
50

51
# Optional: patterns to ignore during parsing
52
autoapi_ignore = ['*migrations*', '*tests*']
53
```
54

55
When documentation is built, AutoAPI will generate API documentation into an `autoapi/` directory and automatically add an entry to your top-level table of contents.
56

57
## Architecture
58

59
AutoAPI uses a multi-stage processing pipeline:
60

61
- **Parser**: Uses astroid to parse Python source code into AST representations without importing
62
- **Mapper**: Converts parsed data into documentation objects and handles cross-references
63
- **Objects**: Python object hierarchy (PythonModule, PythonClass, PythonFunction, etc.) that represent code entities
64
- **Documenters**: Sphinx autodoc-compatible documenters for rendering different object types
65
- **Templates**: Jinja2 templates for generating reStructuredText output files
66
- **Directives**: Custom Sphinx directives for enhanced documentation features
67

68
This design enables reliable documentation generation that works even with complex codebases that have difficult-to-satisfy runtime dependencies.
69

70
## Capabilities
71

72
### Extension Setup and Configuration
73

74
Main Sphinx extension setup function and configuration management. Registers event handlers, configuration values, directives, and documenters with the Sphinx application.
75

76
```python { .api }
77
def setup(app):
78
    """
79
    Main Sphinx extension setup function.
80
    
81
    Parameters:
82
    - app: Sphinx application instance
83
    
84
    Returns:
85
    dict: Extension metadata with parallel read/write safe settings
86
    """
87
```
88

89
[Extension Setup and Configuration](./extension.md)
90

91
### Source Code Parsing and Analysis
92

93
Static analysis of Python source code using astroid to extract API information without importing modules. Handles complex parsing scenarios including type annotations, decorators, and inheritance.
94

95
```python { .api }
96
class Parser:
97
    """Parser for Python source code using astroid."""
98
    
99
    def parse_file(self, file_path: str): ...
100
    def parse_file_in_namespace(self, file_path: str, dir_root: str): ...
101
    def parse(self, node): ...
102
```
103

104
[Source Code Parsing and Analysis](./parsing.md)
105

106
### Documentation Object Model
107

108
Object hierarchy representing parsed Python code entities. Provides structured representation of modules, classes, functions, and other code constructs with rendering capabilities.
109

110
```python { .api }
111
class PythonObject:
112
    """Base class for representing parsed source code entities."""
113
    
114
    name: str
115
    qual_name: str
116
    id: str
117
    children: list['PythonObject']
118
    docstring: str
119
    imported: bool
120
    inherited: bool
121
    
122
    def render(self, **kwargs): ...
123
```
124

125
[Documentation Object Model](./objects.md)
126

127
### Documentation Generation and Mapping
128

129
Core mapping functionality that converts parsed source code into documentation structure. Handles file discovery, content organization, and output generation.
130

131
```python { .api }
132
class Mapper:
133
    """Maps source code to documentation objects."""
134
    
135
    def load(self, patterns: list[str], dirs: list[str], ignore: list[str]) -> bool: ...
136
    def map(self, options: list[str]) -> None: ...
137
    def output_rst(self, source_suffix: str = '.rst') -> None: ...
138
```
139

140
[Documentation Generation and Mapping](./generation.md)
141

142
### Custom Directives and Documenters
143

144
Sphinx directives and autodoc documenters that integrate AutoAPI's static analysis with Sphinx's documentation system. Provides enhanced autosummary, nested parsing, and inheritance diagram capabilities.
145

146
```python { .api }
147
class AutoapiSummary(Autosummary):
148
    """Autosummary directive using static analysis."""
149
    
150
    def get_items(self, names: list[str]): ...
151

152
class NestedParse(Directive):
153
    """Nested parsing directive for removing duplicate headings."""
154
    
155
    def run(self): ...
156

157
class AutoapiInheritanceDiagram(sphinx.ext.inheritance_diagram.InheritanceDiagram):
158
    """Enhanced inheritance diagram directive using static analysis."""
159
    
160
    def run(self): ...
161
```
162

163
[Custom Directives and Documenters](./directives.md)
164

165
## Configuration Options
166

167
AutoAPI provides extensive configuration through Sphinx config values:
168

169
```python { .api }
170
# Core configuration
171
autoapi_dirs: list[str]  # Required: directories to scan
172
autoapi_root: str  # Output directory (default: 'autoapi')
173
autoapi_file_patterns: list[str]  # File patterns to include
174
autoapi_ignore: list[str]  # Patterns to ignore
175

176
# Documentation control
177
autoapi_generate_api_docs: bool  # Generate documentation files
178
autoapi_add_toctree_entry: bool  # Add to table of contents
179
autoapi_keep_files: bool  # Keep generated files after build
180

181
# Content options
182
autoapi_options: list[str]  # Documentation options
183
autoapi_member_order: str  # Member ordering ('bysource', 'alphabetical', 'groupwise')
184
autoapi_own_page_level: str  # Level for separate pages ('module', 'class', etc.)
185

186
# Python-specific options
187
autoapi_python_class_content: str  # Class docstring content ('class', 'both', 'init')
188
autoapi_python_use_implicit_namespaces: bool  # Support PEP 420 namespaces
189

190
# Advanced options
191
autoapi_template_dir: str  # Custom template directory
192
autoapi_include_summaries: bool  # Include summary tables
193
autoapi_prepare_jinja_env: callable  # Custom Jinja environment setup
194
```
195

196
## Events
197

198
Custom Sphinx events for extending AutoAPI behavior:
199

200
```python { .api }
201
# Event: autoapi-skip-member
202
# Fired to determine if a member should be skipped from documentation
203
# Parameters: app, what, name, obj, skip, options
204
```
205

206
## Version Information
207

208
```python { .api }
209
__version__: str  # "3.6.0"
210
__version_info__: tuple[int, int, int]  # (3, 6, 0)
211
```