Extension Setup and Configuration

def setup(app):
    """
    Main Sphinx extension setup function that registers AutoAPI components.
    
    Args:
        app: Sphinx application instance to configure
        
    Returns:
        dict: Extension metadata with parallel read/write safe settings
        
    This function:
    - Registers custom configuration values
    - Adds custom directives and documenters  
    - Registers event handlers
    - Sets up template directories
    - Configures AutoAPI processing pipeline
    """

import autoapi

# Required configuration
autoapi_dirs: list[str]
"""Required. Directories to scan for source code files."""

# Output control
autoapi_root: str = "autoapi"
"""Directory name for generated API documentation."""

autoapi_generate_api_docs: bool = True
"""Whether to generate API documentation files."""

autoapi_add_toctree_entry: bool = True
"""Whether to add AutoAPI entry to table of contents."""

autoapi_keep_files: bool = False
"""Whether to keep generated .rst files after build."""

# File discovery
autoapi_file_patterns: list[str] = ["*.py", "*.pyi"]
"""File patterns to include during source discovery."""

autoapi_ignore: list[str] = ["*migrations*"]
"""Patterns to ignore during source parsing."""

# Documentation options
autoapi_options: list[str] = [
    "members", "undoc-members", "private-members",
    "show-inheritance", "show-module-summary",
    "special-members", "imported-members"
]
"""Documentation generation options."""

autoapi_member_order: str = "bysource"
"""Member ordering: 'bysource', 'alphabetical', or 'groupwise'."""

autoapi_own_page_level: str = "module"
"""Level at which objects get their own page: 'module', 'class', 'function'."""

# Python-specific options
autoapi_python_class_content: str = "class"
"""Class docstring content: 'class', 'both', or 'init'."""

autoapi_python_use_implicit_namespaces: bool = False
"""Support for PEP 420 implicit namespace packages."""

# Template customization
autoapi_template_dir: str = None
"""Custom template directory for overriding default templates."""

autoapi_include_summaries: bool = None
"""Whether to include summary tables in generated docs."""

autoapi_prepare_jinja_env: callable = None
"""Custom function to prepare Jinja environment."""

def run_autoapi(app):
    """
    Core AutoAPI processing function triggered during Sphinx build.
    
    Args:
        app: Sphinx application instance
        
    This function:
    - Creates the Mapper instance
    - Loads and parses source files
    - Generates documentation objects
    - Outputs .rst files
    """

def source_read(app, docname, source):
    """
    Event handler for source file reading to populate annotations.
    
    Args:
        app: Sphinx application instance
        docname (str): Name of the document being read
        source (list): List containing source content
        
    Populates type annotations from Sphinx environment data.
    """

def build_finished(app, exception):
    """
    Event handler for build completion cleanup.
    
    Args:
        app: Sphinx application instance
        exception: Any exception that occurred during build
        
    Removes generated .rst files if autoapi_keep_files is False.
    """

def doctree_read(app, doctree):
    """
    Event handler for injecting AutoAPI into table of contents.
    
    Args:
        app: Sphinx application instance
        doctree: Document tree being processed
        
    Dynamically adds AutoAPI documentation to TOC tree structure.
    """

def viewcode_find(app, modname):
    """
    Event handler for viewcode extension integration.
    
    Args:
        app: Sphinx application instance
        modname (str): Module name being requested
        
    Returns:
        tuple: (source_code, locations_dict) or None if not found
        
    Provides source code locations for Sphinx viewcode extension.
    """

def viewcode_follow_imported(app, modname, attribute):
    """
    Event handler for following imported references in viewcode.
    
    Args:
        app: Sphinx application instance
        modname (str): Module name containing the import
        attribute (str): Attribute name being followed
        
    Returns:
        str: Module name containing the actual definition, or None
        
    Resolves imported attribute references for viewcode links.
    """

# Event: autoapi-skip-member
"""
Custom event fired to determine if a member should be skipped.

Parameters:
    app: Sphinx application instance
    what (str): Type of object ('module', 'class', 'method', etc.)
    name (str): Name of the member
    obj: AutoAPI object being processed
    skip (bool): Current skip status
    options (dict): AutoAPI options

Returns:
    bool: True to skip the member, False to include it
"""

_DEFAULT_FILE_PATTERNS = ["*.py", "*.pyi"]
"""Default file patterns for source discovery."""

_DEFAULT_IGNORE_PATTERNS = ["*migrations*"]  
"""Default patterns to ignore during parsing."""

_DEFAULT_OPTIONS = [
    "members", "undoc-members", "private-members",
    "show-inheritance", "show-module-summary", 
    "special-members", "imported-members"
]
"""Default AutoAPI documentation options."""

_VALID_PAGE_LEVELS = ["module", "class", "function", "method"]
"""Valid values for autoapi_own_page_level configuration."""

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

# Required: specify source directories
autoapi_dirs = ['src', 'my_package']

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

autoapi_root = 'api'
autoapi_file_patterns = ['*.py']
autoapi_ignore = ['*tests*', '*migrations*']
autoapi_python_class_content = 'both'