or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

directives.mdextension.mdgeneration.mdindex.mdobjects.mdparsing.md
tile.json

tessl/pypi-sphinx-autoapi

Sphinx extension for automatically generating complete API documentation from source code without requiring the project to be loaded, run, or imported

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/sphinx-autoapi@3.6.x

To install, run

npx @tessl/cli install tessl/pypi-sphinx-autoapi@3.6.0

index.mddocs/

Sphinx AutoAPI

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.

Package Information

  • Package Name: sphinx-autoapi
  • Language: Python
  • Installation: pip install sphinx-autoapi
  • Minimum Python Version: 3.9
  • Dependencies: astroid, Jinja2, PyYAML, sphinx>=7.4.0

Core Imports

import autoapi

For Sphinx configuration:

# In conf.py
extensions.append('autoapi.extension')

Basic Usage

# Add to Sphinx conf.py
extensions = ['autoapi.extension']

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

# Optional: customize behavior
autoapi_options = [
    'members',
    'undoc-members', 
    'private-members',
    'show-inheritance',
    'show-module-summary',
    'special-members',
    'imported-members',
]

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

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

# Optional: patterns to ignore during parsing
autoapi_ignore = ['*migrations*', '*tests*']

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.

Architecture

AutoAPI uses a multi-stage processing pipeline:

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

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

Capabilities

Extension Setup and Configuration

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

def setup(app):
    """
    Main Sphinx extension setup function.
    
    Parameters:
    - app: Sphinx application instance
    
    Returns:
    dict: Extension metadata with parallel read/write safe settings
    """

Extension Setup and Configuration

Source Code Parsing and Analysis

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.

class Parser:
    """Parser for Python source code using astroid."""
    
    def parse_file(self, file_path: str): ...
    def parse_file_in_namespace(self, file_path: str, dir_root: str): ...
    def parse(self, node): ...

Source Code Parsing and Analysis

Documentation Object Model

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

class PythonObject:
    """Base class for representing parsed source code entities."""
    
    name: str
    qual_name: str
    id: str
    children: list['PythonObject']
    docstring: str
    imported: bool
    inherited: bool
    
    def render(self, **kwargs): ...

Documentation Object Model

Documentation Generation and Mapping

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

class Mapper:
    """Maps source code to documentation objects."""
    
    def load(self, patterns: list[str], dirs: list[str], ignore: list[str]) -> bool: ...
    def map(self, options: list[str]) -> None: ...
    def output_rst(self, source_suffix: str = '.rst') -> None: ...

Documentation Generation and Mapping

Custom Directives and Documenters

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.

class AutoapiSummary(Autosummary):
    """Autosummary directive using static analysis."""
    
    def get_items(self, names: list[str]): ...

class NestedParse(Directive):
    """Nested parsing directive for removing duplicate headings."""
    
    def run(self): ...

class AutoapiInheritanceDiagram(sphinx.ext.inheritance_diagram.InheritanceDiagram):
    """Enhanced inheritance diagram directive using static analysis."""
    
    def run(self): ...

Custom Directives and Documenters

Configuration Options

AutoAPI provides extensive configuration through Sphinx config values:

# Core configuration
autoapi_dirs: list[str]  # Required: directories to scan
autoapi_root: str  # Output directory (default: 'autoapi')
autoapi_file_patterns: list[str]  # File patterns to include
autoapi_ignore: list[str]  # Patterns to ignore

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

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

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

# Advanced options
autoapi_template_dir: str  # Custom template directory
autoapi_include_summaries: bool  # Include summary tables
autoapi_prepare_jinja_env: callable  # Custom Jinja environment setup

Events

Custom Sphinx events for extending AutoAPI behavior:

# Event: autoapi-skip-member
# Fired to determine if a member should be skipped from documentation
# Parameters: app, what, name, obj, skip, options

Version Information

__version__: str  # "3.6.0"
__version_info__: tuple[int, int, int]  # (3, 6, 0)