Configuration

Sphinx configuration values that control the behavior of sphinx-automodapi directives. These settings are added to your Sphinx conf.py file to customize how the extension generates documentation.

Capabilities

automodapi Configuration

Settings that control the behavior of the automodapi directive and its document generation process.

# conf.py settings
automodapi_inheritance_diagram: bool = True
automodapi_toctreedirnm: str = 'api'
automodapi_writereprocessed: bool = False

automodapi_inheritance_diagram

Controls whether inheritance diagrams are generated by default for classes in automodapi documentation.

Type: bool
Default: True
Usage: Can be overridden per-directive with :inheritance-diagram: or :no-inheritance-diagram: options

# In conf.py
automodapi_inheritance_diagram = False  # Disable diagrams globally

automodapi_toctreedirnm

Specifies the directory name used for API documentation in the toctree structure.

Type: str
Default: 'api'
Usage: Controls where generated API files are organized in the documentation structure

# In conf.py
automodapi_toctreedirnm = 'reference'  # Use 'reference' instead of 'api'

automodapi_writereprocessed

Controls whether reprocessed files are written to disk during documentation generation.

Type: bool
Default: False
Usage: Primarily for debugging and development of the extension itself

# In conf.py
automodapi_writereprocessed = True  # Enable for debugging

automodsumm Configuration

Settings that control the behavior of automodsumm and automod-diagram directives.

# conf.py settings
automodsumm_writereprocessed: bool = False
automodsumm_inherited_members: bool = False
automodsumm_included_members: list[str] = ['__init__', '__call__']
automodsumm_properties_are_attributes: bool = True

automodsumm_writereprocessed

Controls whether reprocessed autosummary files are written to disk.

Type: bool
Default: False
Usage: For debugging autosummary generation process

# In conf.py
automodsumm_writereprocessed = True

automodsumm_inherited_members

Global setting for whether to include inherited class members in documentation.

Type: bool
Default: False
Usage: Can be overridden per-directive with :inherited-members: or :no-inherited-members: options

# In conf.py
automodsumm_inherited_members = True  # Include inherited members globally

automodsumm_included_members

List of special method names to include in documentation even if they would normally be filtered out.

Type: list[str]
Default: ['__init__', '__call__']
Usage: Controls which dunder methods appear in generated documentation

# In conf.py
automodsumm_included_members = ['__init__', '__call__', '__enter__', '__exit__']

automodsumm_properties_are_attributes

Controls whether class properties are treated as attributes in the documentation.

Type: bool
Default: True
Usage: Affects how properties are categorized and displayed

# In conf.py
automodsumm_properties_are_attributes = False  # Treat properties separately

Configuration Setup

These configuration values are automatically registered when the extension is loaded. Add them to your conf.py file:

def setup(app: Sphinx) -> dict[str, bool]:
    """
    Register configuration values with Sphinx.
    
    Each configuration value is registered with:
    - Default value
    - Rebuild requirement ('env' for environment, True for full rebuild)
    """

Complete Example Configuration

# conf.py
extensions = [
    'sphinx_automodapi.automodapi',
    'sphinx_automodapi.smart_resolver',
]

# automodapi settings
automodapi_inheritance_diagram = True
automodapi_toctreedirnm = 'api'
automodapi_writereprocessed = False

# automodsumm settings  
automodsumm_writereprocessed = False
automodsumm_inherited_members = False
automodsumm_included_members = ['__init__', '__call__']
automodsumm_properties_are_attributes = True

Configuration Value Types

# Type definitions for configuration values
ConfigValue = Union[bool, str, list[str]]

# Rebuild requirement types
RebuildRequirement = Union[bool, str]  # True, False, 'env', or 'html'

Advanced Configuration

Extension Dependencies

sphinx-automodapi automatically sets up required extensions:

# Automatically loaded extensions
'sphinx.ext.autosummary'      # For summary table generation
'sphinx.ext.inheritance_diagram'  # For class diagrams

Template Customization

The extension includes custom templates that can be overridden:

• autosummary_core/base.rst: Base template for autosummary
• autosummary_core/class.rst: Template for class documentation
• autosummary_core/module.rst: Template for module documentation

To customize templates, create corresponding files in your documentation's _templates/autosummary_core/ directory.

Integration Notes

Configuration values affect different aspects of the documentation generation:

1. Build-time settings: Control how files are processed and generated
2. Runtime settings: Affect directive behavior during document parsing
3. Output settings: Control the format and organization of generated content

The configuration system integrates with Sphinx's standard configuration mechanism, ensuring that settings are properly validated and available throughout the documentation build process.