0
# Sphinx Automodapi
1

2
A Sphinx extension that automatically generates comprehensive API documentation for entire Python modules. Originally developed for the Astropy project, sphinx-automodapi eliminates the need for manual API documentation maintenance by automatically discovering and documenting all public module members, including their docstrings, function signatures, and inheritance relationships.
3

4
## Package Information
5

6
- **Package Name**: sphinx-automodapi
7
- **Language**: Python
8
- **Installation**: `pip install sphinx-automodapi`
9
- **Dependencies**: sphinx>=4, packaging
10

11
## Core Imports
12

13
```python
14
import sphinx_automodapi
15
```
16

17
For configuring the extension in Sphinx `conf.py`:
18

19
```python
20
extensions = [
21
    'sphinx_automodapi.automodapi',
22
    'sphinx_automodapi.smart_resolver',
23
    # Other extensions...
24
]
25
```
26

27
## Basic Usage
28

29
Add to your Sphinx `conf.py`:
30

31
```python
32
extensions = ['sphinx_automodapi.automodapi']
33
```
34

35
Then use directives in your reStructuredText files:
36

37
```rst
38
.. automodapi:: mypackage.mymodule
39
```
40

41
This generates complete API documentation including:
42
- Module docstring
43
- Summary tables of functions, classes, and variables
44
- Individual detailed documentation for each API member
45
- Optional inheritance diagrams for classes
46

47
## Architecture
48

49
sphinx-automodapi uses Sphinx's directive system to extend reStructuredText with new documentation directives. The extension integrates deeply with Sphinx's autodoc system and provides three core components:
50

51
- **automodapi directive**: Generates complete module documentation with summary tables and detailed member docs
52
- **automodsumm directive**: Creates summary tables for module contents with flexible filtering
53
- **automod-diagram directive**: Generates inheritance diagrams for classes in modules
54
- **Smart resolver**: Handles reference resolution between API locations and source locations
55
- **Autodoc enhancements**: Improves attribute documentation for complex class hierarchies
56

57
## Capabilities
58

59
### Core Directives
60

61
The main documentation generation directives that form the heart of sphinx-automodapi's functionality. These directives automatically discover module contents and generate comprehensive documentation.
62

63
```python { .api }
64
# automodapi directive - generates complete module documentation
65
# Usage: .. automodapi:: module.name
66

67
# automodsumm directive - generates summary tables
68
# Usage: .. automodsumm:: module.name
69

70
# automod-diagram directive - generates inheritance diagrams
71
# Usage: .. automod-diagram:: module.name
72
```
73

74
[Core Directives](./directives.md)
75

76
### Utility Functions
77

78
Functions for discovering module objects, processing text, and handling autosummary integration. These utilities power the directive functionality and can be used programmatically.
79

80
```python { .api }
81
def find_mod_objs(modname: str, onlylocals: bool | list = False, sort: bool = False) -> tuple[list[str], list[str], list[object]]
82
def cleanup_whitespace(text: str) -> str
83
def find_autosummary_in_lines_for_automodsumm(lines: list[str], module: str = None, filename: str = None) -> list[tuple]
84
```
85

86
[Utilities](./utilities.md)
87

88
### Configuration Options
89

90
Sphinx configuration values that control the behavior of sphinx-automodapi directives, including inheritance diagram display, file organization, and processing options.
91

92
```python { .api }
93
# Configuration values for conf.py
94
automodapi_inheritance_diagram: bool = True
95
automodapi_toctreedirnm: str = 'api'
96
automodapi_writereprocessed: bool = False
97
automodsumm_writereprocessed: bool = False
98
automodsumm_inherited_members: bool = False
99
automodsumm_included_members: list = ['__init__', '__call__']
100
automodsumm_properties_are_attributes: bool = True
101
```
102

103
[Configuration](./configuration.md)
104

105
### Smart Reference Resolution
106

107
Handles the mapping between API locations (where users import from) and source locations (where code is defined), ensuring that cross-references work correctly in complex package hierarchies.
108

109
```python { .api }
110
def process_docstring(app, what: str, name: str, obj, options, lines: list)
111
def missing_reference_handler(app, env, node, contnode)
112
def merge_mapping(app, env, docnames, env_other)
113
```
114

115
[Smart Resolution](./smart-resolution.md)
116

117
### Autodoc Enhancements
118

119
Enhancements to Sphinx's autodoc functionality that improve attribute documentation for complex class hierarchies, metaclass properties, and dataclass fields.
120

121
```python { .api }
122
def type_object_attrgetter(obj: type, attr: str, *defargs) -> object
123
def setup(app: Sphinx) -> dict[str, bool]
124
```
125

126
[Autodoc Enhancements](./autodoc-enhancements.md)
127

128
## Types
129

130
```python { .api }
131
# Sphinx application and environment types
132
from sphinx.application import Sphinx
133
from sphinx.environment import BuildEnvironment
134

135
# Docutils node types
136
from docutils.nodes import Node, Element
137

138
# Extension setup return type
139
SetupReturn = dict[str, bool]  # {'parallel_read_safe': bool, 'parallel_write_safe': bool}
140
```