tessl/pypi-sphinx-automodapi
Sphinx extension for auto-generating API documentation for entire modules
—
directives.mddocs/
Core Directives
The main documentation generation directives that automatically discover module contents and generate comprehensive documentation. These directives form the core functionality of sphinx-automodapi.
Capabilities
automodapi Directive
Generates complete API documentation for a module including the module docstring, summary tables of functions and classes, detailed documentation for each member, and optional inheritance diagrams.
.. automodapi:: module.name
:include-all-objects:
:inheritance-diagram:
:no-inheritance-diagram:
:skip: obj1, obj2
:include: obj1, obj2
:no-main-docstr:
:headings: -^
:no-heading:
:sort:Parameters:
module.name: The fully qualified name of the module to document:include-all-objects:: Include variables and other objects, not just functions and classes:inheritance-diagram:/:no-inheritance-diagram:: Control inheritance diagram display:skip: obj1, obj2: Skip specified objects from documentation:include: obj1, obj2: Include only specified objects in documentation:no-main-docstr:: Skip the module's main docstring:headings: str: Characters to use for section headings (default: "-^"):no-heading:: Don't create a top-level heading for the module:sort:: Sort objects alphabetically
Usage Example
Basic usage:
.. automodapi:: mypackage.utils
With options:
.. automodapi:: mypackage.core
:include-all-objects:
:skip: internal_helper
:sort:automodsumm Directive
Generates autosummary-style tables for module contents with automatic discovery and flexible filtering options. Unlike Sphinx's built-in autosummary, this doesn't require manually listing each item.
.. automodsumm:: module.name
:classes-only:
:functions-only:
:variables-only:
:skip: obj1, obj2
:allowed-package-names: pkg1, pkg2
:inherited-members:
:no-inherited-members:
:sort:Parameters:
module.name: The fully qualified name of the module to summarize:classes-only:: Include only classes in the summary table:functions-only:: Include only functions in the summary table:variables-only:: Include only variables in the summary table:skip: obj1, obj2: Skip specified objects from the summary:allowed-package-names: pkg1, pkg2: Limit objects to specified packages:inherited-members:/:no-inherited-members:: Control inherited member inclusion:sort:: Sort objects alphabetically
Note: The filtering options :classes-only:, :functions-only:, and :variables-only: are mutually exclusive.
Usage Example
Basic summary:
.. automodsumm:: mypackage.models
Functions only:
.. automodsumm:: mypackage.helpers
:functions-only:
:skip: _internal_helper
:sort:automod-diagram Directive
Generates inheritance diagrams for classes found in a module using Graphviz. This directive extends Sphinx's inheritance_diagram functionality with automatic class discovery.
.. automod-diagram:: module.nameParameters:
module.name: The fully qualified name of the module containing classes to diagram
This directive inherits all options from sphinx.ext.inheritance_diagram.InheritanceDiagram, including:
:parts: N: Show only the last N parts of class names:private-bases:: Include private base classes:caption: text: Add a caption to the diagram
Usage Example
Basic inheritance diagram:
.. automod-diagram:: mypackage.models
With options:
.. automod-diagram:: mypackage.widgets
:parts: 2
:caption: Widget class hierarchyDirective Implementation Details
Class Hierarchy
# Base classes for the directives
from sphinx.ext.autosummary import Autosummary
from sphinx.ext.inheritance_diagram import InheritanceDiagram
class Automodsumm(Autosummary):
"""Implements the automodsumm directive"""
class Automoddiagram(InheritanceDiagram):
"""Implements the automod-diagram directive"""Processing Functions
def process_automodapi(app: Sphinx, docname: str, source: list[str]) -> None:
"""
Sphinx event handler that processes automodapi directives in source files.
Parameters:
- app: Sphinx application instance
- docname: Name of the document being processed
- source: List containing the source content (modified in-place)
"""
def process_automodsumm_generation(app: Sphinx) -> None:
"""
Sphinx event handler that processes automodsumm directive generation.
Parameters:
- app: Sphinx application instance
"""
def automodapi_replace(sourcestr: str, app: Sphinx, dotoctree: bool = True,
docname: str = None, warnings: bool = True) -> str:
"""
Replace automodapi directives in source string with generated documentation.
Parameters:
- sourcestr: Source string containing automodapi directives
- app: Sphinx application instance
- dotoctree: Whether to include toctree directives
- docname: Name of the current document
- warnings: Whether to issue warnings for problems
Returns:
- str: Source string with automodapi directives replaced
"""Integration with Sphinx
These directives integrate with Sphinx through the extension setup system:
def setup(app: Sphinx) -> dict[str, bool]:
"""
Set up the directives extension with Sphinx.
Registers:
- automod-diagram directive
- automodsumm directive
- Event handlers for processing (source-read, builder-inited)
- Configuration values
Returns:
- dict: Parallel processing compatibility flags
Extensions loaded:
- sphinx.ext.autosummary (for summary table generation)
- sphinx.ext.inheritance_diagram (for class diagrams)
- sphinx_automodapi.autodoc_enhancements (for enhanced attribute access)
"""Install with Tessl CLI
npx tessl i tessl/pypi-sphinx-automodapi