Sphinx Automodapi

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.

Package Information

• Package Name: sphinx-automodapi
• Language: Python
• Installation: pip install sphinx-automodapi
• Dependencies: sphinx>=4, packaging

Core Imports

import sphinx_automodapi

For configuring the extension in Sphinx conf.py:

extensions = [
    'sphinx_automodapi.automodapi',
    'sphinx_automodapi.smart_resolver',
    # Other extensions...
]

Basic Usage

Add to your Sphinx conf.py:

extensions = ['sphinx_automodapi.automodapi']

Then use directives in your reStructuredText files:

.. automodapi:: mypackage.mymodule

This generates complete API documentation including:

• Module docstring
• Summary tables of functions, classes, and variables
• Individual detailed documentation for each API member
• Optional inheritance diagrams for classes

Architecture

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:

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

Capabilities

Core Directives

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

# automodapi directive - generates complete module documentation
# Usage: .. automodapi:: module.name

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

# automod-diagram directive - generates inheritance diagrams
# Usage: .. automod-diagram:: module.name

Core Directives

Utility Functions

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

def find_mod_objs(modname: str, onlylocals: bool | list = False, sort: bool = False) -> tuple[list[str], list[str], list[object]]
def cleanup_whitespace(text: str) -> str
def find_autosummary_in_lines_for_automodsumm(lines: list[str], module: str = None, filename: str = None) -> list[tuple]

Utilities

Configuration Options

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

# Configuration values for conf.py
automodapi_inheritance_diagram: bool = True
automodapi_toctreedirnm: str = 'api'
automodapi_writereprocessed: bool = False
automodsumm_writereprocessed: bool = False
automodsumm_inherited_members: bool = False
automodsumm_included_members: list = ['__init__', '__call__']
automodsumm_properties_are_attributes: bool = True

Configuration

Smart Reference Resolution

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.

def process_docstring(app, what: str, name: str, obj, options, lines: list)
def missing_reference_handler(app, env, node, contnode)
def merge_mapping(app, env, docnames, env_other)

Smart Resolution

Autodoc Enhancements

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

def type_object_attrgetter(obj: type, attr: str, *defargs) -> object
def setup(app: Sphinx) -> dict[str, bool]

Autodoc Enhancements

Types

# Sphinx application and environment types
from sphinx.application import Sphinx
from sphinx.environment import BuildEnvironment

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

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