Custom Directives and Documenters

class AutoapiSummary(Autosummary):
    """
    Enhanced autosummary directive using AutoAPI's static analysis.
    
    Extends Sphinx's standard autosummary directive to work with AutoAPI's
    statically analyzed objects instead of requiring imports. Generates
    summary tables with proper cross-references.
    
    Inherits from: sphinx.ext.autosummary.Autosummary
    """
    
    def get_items(self, names: list[str]):
        """
        Get summary items for the specified names using static analysis.
        
        Args:
            names (list[str]): Object names to summarize
            
        Returns:
            list[tuple]: List of (name, signature, summary, real_name) tuples
            
        Uses AutoAPI's parsed objects to generate summaries without
        requiring imports or code execution.
        """

class NestedParse(Directive):
    """
    Directive for nested reStructuredText parsing with heading adjustment.
    
    Handles nested parsing of reStructuredText content while automatically
    removing or adjusting duplicate headings that would conflict with
    the containing document structure.
    
    Inherits from: docutils.parsers.rst.Directive
    """
    
    def run(self):
        """
        Execute the nested parsing with heading removal.
        
        Returns:
            list[Node]: Parsed document nodes with adjusted headings
            
        Processes nested reStructuredText content and removes the first
        heading to prevent title conflicts in generated documentation.
        """

class AutoapiInheritanceDiagram(sphinx.ext.inheritance_diagram.InheritanceDiagram):
    """
    Enhanced inheritance diagram directive using AutoAPI's static analysis.
    
    Extends Sphinx's standard inheritance_diagram directive to work with 
    AutoAPI's statically analyzed objects instead of requiring imports.
    Generates class inheritance diagrams using static analysis.
    
    Inherits from: sphinx.ext.inheritance_diagram.InheritanceDiagram
    """
    
    def run(self):
        """
        Generate inheritance diagram using static analysis.
        
        Returns:
            list[Node]: Inheritance diagram nodes
            
        Uses AutoAPI's static analysis to generate inheritance diagrams
        without requiring imports or code execution.
        """

from autoapi.directives import AutoapiSummary, NestedParse

from autoapi.inheritance_diagrams import AutoapiInheritanceDiagram

class AutoapiDocumenter(Documenter):
    """
    Base documenter class for all AutoAPI objects.
    
    Provides common functionality for documenting statically analyzed
    objects without requiring imports. All specific documenters inherit
    from this base class.
    
    Inherits from: sphinx.ext.autodoc.Documenter
    """
    
    def get_attr(self, obj, name, *defargs):
        """
        Get attribute from AutoAPI object.
        
        Args:
            obj: AutoAPI object instance
            name (str): Attribute name to retrieve
            *defargs: Default values if attribute not found
            
        Returns:
            Any: Attribute value or default
            
        Retrieves attributes from AutoAPI objects using static analysis
        data instead of runtime introspection.
        """
    
    def import_object(self, raiseerror: bool = False):
        """
        Import/load the AutoAPI object for documentation.
        
        Args:
            raiseerror (bool): Whether to raise errors on import failure
            
        Returns:
            bool: True if object was successfully loaded
            
        Loads objects from AutoAPI's static analysis results rather
        than performing runtime imports.
        """

class AutoapiFunctionDocumenter(AutoapiDocumenter):
    """
    Documenter for standalone functions.
    
    Handles documentation of module-level functions with complete
    signature information, parameter documentation, and return types
    extracted from static analysis.
    
    Supports:
    - Function signatures with type annotations
    - Parameter documentation from docstrings
    - Return type information
    - Decorator information
    - Overload handling
    """

class AutoapiMethodDocumenter(AutoapiDocumenter):
    """
    Documenter for class methods.
    
    Handles all types of class methods including instance methods,
    static methods, class methods, and special methods with proper
    inheritance and override detection.
    
    Supports:
    - Method type identification (static, class, instance)
    - Inheritance relationship documentation
    - Abstract method identification
    - Property method integration
    """

class AutoapiClassDocumenter(AutoapiDocumenter):
    """
    Documenter for Python classes.
    
    Provides comprehensive class documentation including inheritance
    hierarchies, member organization, and constructor documentation
    with full static analysis integration.
    
    Supports:
    - Class inheritance documentation
    - Method Resolution Order (MRO)
    - Constructor parameter documentation
    - Member organization and filtering
    - Abstract class handling
    """

class AutoapiExceptionDocumenter(AutoapiDocumenter):
    """
    Documenter for exception classes.
    
    Specialized class documenter for exception classes with additional
    context for error handling and exception hierarchy documentation.
    
    Provides exception-specific templates and documentation patterns
    while maintaining full class documentation capabilities.
    """

class AutoapiPropertyDocumenter(AutoapiDocumenter):
    """
    Documenter for Python properties.
    
    Handles @property decorated methods with getter, setter, and
    deleter documentation, including type information and proper
    cross-referencing.
    
    Supports:
    - Property getter documentation
    - Setter and deleter methods
    - Type annotation integration
    - Read-only property identification
    """

class AutoapiAttributeDocumenter(AutoapiDocumenter):
    """
    Documenter for class and instance attributes.
    
    Documents class variables, instance attributes, and annotated
    attributes with type information and value documentation.
    
    Supports:
    - Class variable documentation
    - Instance attribute identification
    - Type annotation display
    - Default value representation
    """

class AutoapiDataDocumenter(AutoapiDocumenter):
    """
    Documenter for module-level data and constants.
    
    Handles module-level variables, constants, and configuration
    values with type annotations and value documentation.
    
    Supports:
    - Constant identification and documentation
    - Type annotation integration
    - Value representation for simple types
    - Import alias resolution
    """

class AutoapiDecoratorDocumenter(AutoapiDocumenter):
    """
    Documenter for decorators and decorator factories.
    
    Provides specialized documentation for decorator functions with
    proper signature handling and usage examples.
    
    Supports:
    - Decorator signature documentation
    - Decorator factory parameter handling
    - Usage example integration
    - Cross-references to decorated objects
    """

class AutoapiModuleDocumenter(AutoapiDocumenter):
    """
    Documenter for Python modules.
    
    Provides comprehensive module documentation with member summaries,
    import organization, and cross-package references.
    
    Supports:
    - Module-level docstring processing
    - Member summary generation
    - Import statement documentation
    - Submodule cross-references
    """

# Documenters are registered with Sphinx during extension setup:
"""
app.add_autodocumenter(AutoapiModuleDocumenter)
app.add_autodocumenter(AutoapiClassDocumenter)
app.add_autodocumenter(AutoapiFunctionDocumenter)
app.add_autodocumenter(AutoapiMethodDocumenter)
app.add_autodocumenter(AutoapiPropertyDocumenter)
app.add_autodocumenter(AutoapiAttributeDocumenter)
app.add_autodocumenter(AutoapiDataDocumenter)
app.add_autodocumenter(AutoapiDecoratorDocumenter)
app.add_autodocumenter(AutoapiExceptionDocumenter)
"""

# Directives are registered during extension setup:
"""
app.add_directive('autoapi-nested-parse', NestedParse)
app.add_directive('autoapisummary', AutoapiSummary)
"""

# Documenters leverage AutoAPI's static analysis:
"""
- No runtime imports required
- Safe documentation of broken/incomplete code
- Type annotation preservation
- Cross-reference resolution without execution
- Inheritance analysis without class instantiation
"""

# Documenters work with AutoAPI templates:
"""
- Object-specific template selection
- Context data from static analysis
- Custom template support
- Jinja2 filter integration
- reStructuredText generation
"""

.. autoapisummary::
   :toctree: _autosummary

   mymodule.MyClass
   mymodule.my_function
   mymodule.CONSTANT

.. autoapi-nested-parse::
   
   This content will be parsed with heading adjustment.
   
   Title That Would Conflict
   =========================
   
   This title will be removed or adjusted.

# Documenters integrate seamlessly with autodoc:
"""
.. autoclass:: mymodule.MyClass
   :members:
   :show-inheritance:

.. autofunction:: mymodule.my_function

.. autodata:: mymodule.CONSTANT
"""