Sphinx Extension

def setup(app, *args, **kwargs):
    """
    Main Sphinx extension setup function.
    
    Registers numpydoc with Sphinx and configures all extension functionality
    including docstring processing, signature handling, and custom domains.
    
    Parameters
    ----------
    app : sphinx.application.Sphinx
        The Sphinx application instance
    *args : tuple
        Additional positional arguments (unused)
    **kwargs : dict  
        Additional keyword arguments (unused)
        
    Returns
    -------
    dict
        Extension metadata with version and parallel read/write safety
    """

# From numpydoc.__init__
from numpydoc import setup

def setup(app, *args, **kwargs):
    """
    Package-level setup function that delegates to numpydoc.numpydoc.setup.
    
    This is the main entry point when adding 'numpydoc' to extensions list.
    """

def mangle_docstrings(app, what, name, obj, options, lines):
    """
    Process docstrings during Sphinx autodoc processing.
    
    Transforms NumPy-style docstrings into reStructuredText format,
    handling sections like Parameters, Returns, Examples, etc.
    
    Parameters
    ----------
    app : sphinx.application.Sphinx
        Sphinx application instance
    what : str
        Type of object being documented ('module', 'class', 'function', etc.)
    name : str
        Fully qualified name of the object
    obj : object
        The actual Python object being documented
    options : dict
        Autodoc options for this object
    lines : list of str
        Docstring lines (modified in-place)
    """

def mangle_signature(app, what, name, obj, options, sig, retann):
    """
    Process function signatures during Sphinx autodoc processing.
    
    Handles signature mangling for better display, particularly for
    functions with complex parameter lists or return annotations.
    
    Parameters
    ----------
    app : sphinx.application.Sphinx
        Sphinx application instance
    what : str
        Type of object ('function', 'method', etc.)
    name : str
        Fully qualified name of the object  
    obj : object
        The actual Python object
    options : dict
        Autodoc options
    sig : str or None
        Function signature string
    retann : str or None
        Return annotation string
        
    Returns
    -------
    tuple of (str or None, str or None)
        Modified (signature, return_annotation) or (None, None) for no change
    """

def rename_references(app, what, name, obj, options, lines):
    """
    Decorate references in docstrings for improved cross-linking.
    
    Processes reference patterns to create proper Sphinx cross-references,
    enabling automatic linking between documentation elements.
    
    Parameters
    ----------
    app : sphinx.application.Sphinx
        Sphinx application instance
    what : str
        Type of object being documented
    name : str  
        Fully qualified name of the object
    obj : object
        The actual Python object
    options : dict
        Autodoc options
    lines : list of str
        Docstring lines (modified in-place)
    """

def relabel_references(app, doc):
    """
    Change reference labels to use object names instead of hashes.
    
    Processes the document tree to replace generated reference labels
    with more meaningful names based on the actual object names.
    
    Parameters
    ----------
    app : sphinx.application.Sphinx
        Sphinx application instance
    doc : docutils.nodes.document
        Document node tree
    """

def clean_backrefs(app, doc, docname):
    """
    Remove invalid back-references from the document.
    
    Cleans up broken or invalid back-reference nodes that could
    cause documentation build errors or warnings.
    
    Parameters
    ----------
    app : sphinx.application.Sphinx
        Sphinx application instance
    doc : docutils.nodes.document
        Document node tree  
    docname : str
        Name of the document being processed
    """

class NumpyPythonDomain(ManglingDomainBase, PythonDomain):
    """
    Custom Python domain that handles NumPy-style docstring processing.
    
    Extends Sphinx's built-in Python domain to provide NumPy-specific
    functionality for docstring processing and cross-referencing.
    
    Attributes
    ----------
    name : str
        Domain name ('npy')
    """

class ManglingDomainBase:
    """
    Base class for mangling domains.
    
    Provides common functionality for domains that need to process
    and transform docstrings during the documentation build process.
    """

class NumpyCDomain(ManglingDomainBase, CDomain):
    """
    Custom C domain that handles NumPy-style docstring processing.
    
    Extends Sphinx's built-in C domain to provide NumPy-specific
    functionality for C API documentation with NumPy docstrings.
    
    Attributes  
    ----------
    name : str
        Domain name ('npy-c')
    """

def update_config(app, config=None):
    """
    Update numpydoc configuration based on Sphinx config values.
    
    Synchronizes numpydoc-specific configuration options with the
    Sphinx configuration, applying defaults and validating values.
    
    Parameters
    ----------
    app : sphinx.application.Sphinx
        Sphinx application instance
    config : sphinx.config.Config or None
        Sphinx configuration object (defaults to app.config)
    """

# Configuration values registered with Sphinx
numpydoc_use_plots: bool = False
"""Enable plot directive processing in examples sections."""

numpydoc_show_class_members: bool = True  
"""Show class members in generated documentation."""

numpydoc_show_inherited_class_members: bool = True
"""Show inherited class members in documentation."""

numpydoc_class_members_toctree: bool = True
"""Generate table of contents for class members."""

numpydoc_citation_re: str = "[\\w-]+(?:\\s+[\\w-]+)*"
"""Regular expression pattern for detecting citations."""

numpydoc_attributes_as_param_list: bool = True
"""Format class attributes as parameter lists."""

numpydoc_xref_param_type: bool = False  
"""Enable cross-referencing of parameter types."""

numpydoc_xref_aliases: dict = {}
"""Custom type alias mappings for cross-references."""

numpydoc_xref_ignore: set = set()
"""Set of type names to ignore for cross-referencing."""

numpydoc_validation_checks: set = set()
"""Set of validation check codes to apply."""

numpydoc_validation_exclude: set = set()
"""Set of object patterns to exclude from validation."""

numpydoc_validation_overrides: dict = {}
"""Dictionary mapping object patterns to validation rule overrides."""

HASH_LEN: int = 12
"""Length for reference hash generation in cross-references."""

DEDUPLICATION_TAG: str = "<!-- numpydoc_validation -->"
"""HTML comment tag used to mark processed docstrings."""

# conf.py
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.autosummary', 
    'numpydoc'
]

# Basic numpydoc configuration
numpydoc_use_plots = False
numpydoc_show_class_members = True
numpydoc_validation_checks = {'all'}

# conf.py - Advanced numpydoc setup
numpydoc_xref_param_type = True
numpydoc_xref_aliases = {
    'array_like': ':term:`array_like`',
    'ndarray': 'numpy.ndarray',
    'DataFrame': 'pandas.DataFrame'
}

numpydoc_validation_checks = {
    'all',    # Enable all validation checks
    'GL08',   # Check docstring formatting
    'SS01',   # Check summary sections  
}

numpydoc_validation_exclude = {
    r'\.tests\..*',      # Exclude test modules
    r'.*\._[^.]*$'       # Exclude private modules
}

# Using custom domains in reStructuredText
.. npy:function:: my_function(x, y)

   NumPy-style function with custom domain processing.
   
   Parameters
   ----------
   x : array_like
       Input array
   y : float
       Scaling factor