Jinja Domain

def setup(app):
    """
    Register Jinja domain if Jinja is installed.
    
    Conditionally loads the Jinja domain functionality only when the
    Jinja2 library is available in the environment.
    
    Parameters:
    - app: Sphinx application instance
    """

# RST directive usage:
# .. jinja:filters:: jinja2.filters.FILTERS
#
# Automatically generates documentation for all filters in the mapping

# RST directive usage:
# .. jinja:tests:: jinja2.tests.TESTS
#
# Automatically generates documentation for all tests in the mapping

# RST directive usage:
# .. jinja:nodes:: jinja2.nodes.Node
#
# Recursively documents Node class and all subclasses

class MappedFunctionsDirective(SphinxDirective):
    """
    Generate documentation from Jinja function mappings.
    
    Takes a dictionary mapping names to functions and produces rendered
    documentation with signatures, descriptions, and aliases. Used for
    both filters and tests directives.
    
    Attributes:
    - required_arguments: 1 (import path to mapping dict)
    """
    
    def _build_functions(self):
        """
        Import mapping and build function documentation.
        
        Processes the function mapping to identify aliases, extract
        signatures and docstrings, and prepare documentation content.
        
        Returns:
        list: Rendered Sphinx nodes for function documentation
        """
        
    def _build_table(self):
        """
        Build table of contents for documented functions.
        
        Creates a 5-column CSV table with function names as cross-references,
        organized alphabetically in columns for easy navigation.
        
        Returns:
        list: Rendered Sphinx nodes for the table
        """
        
    def run(self):
        """
        Execute directive processing.
        
        Builds both the function documentation and table of contents,
        returning the table above the detailed documentation.
        
        Returns:
        list: Complete list of rendered Sphinx nodes
        """

class NodesDirective(SphinxDirective):
    """
    Generate documentation for Jinja Node class hierarchies.
    
    Takes a base Node class and recursively documents it and all
    subclasses in depth-first order with parent references.
    
    Attributes:
    - required_arguments: 1 (import path to base Node class)
    """
    
    def run(self):
        """
        Execute directive processing.
        
        Recursively walks the Node class hierarchy and generates
        autodoc-style documentation for each class.
        
        Returns:
        list: Rendered Sphinx nodes for all Node classes
        """

class JinjaDomain(Domain):
    """
    Sphinx domain for Jinja documentation.
    
    Provides jinja:filters, jinja:tests, and jinja:nodes directives
    for comprehensive Jinja2 API documentation.
    
    Attributes:
    - name: "jinja"
    - label: "Jinja"
    - directives: {
        "filters": MappedFunctionsDirective,
        "tests": MappedFunctionsDirective, 
        "nodes": NodesDirective
      }
    """

class JinjaStyle(Style):
    """
    Custom Pygments style for Jinja documentation.
    
    Provides syntax highlighting colors optimized for Jinja templates
    and Python code in Jinja-themed documentation.
    
    Attributes:
    - background_color: "#f8f8f8"
    - default_style: ""
    - styles: dict mapping token types to style strings
    """

def build_function_directive(name, aliases, func):
    """
    Build function directive with signature and documentation.
    
    Extracts function signature, docstring, and handles special cases
    for Jinja filters (removing internal arguments, unwrapping async variants).
    
    Parameters:
    - name: Primary name for the function
    - aliases: List of alternative names for the function
    - func: The function object to document
    
    Returns:
    list: Lines of reStructuredText for the function directive
    """

.. jinja:filters:: jinja2.filters.FILTERS

This creates documentation for all built-in Jinja filters including:
- Function signatures with proper parameter handling
- Complete docstrings
- Alias information (e.g., `e` as alias for `escape`)
- Alphabetical table of contents

.. jinja:tests:: jinja2.tests.TESTS

This creates documentation for all built-in Jinja tests including:
- Boolean test functions (divisibleby, even, odd, etc.)
- String tests (lower, upper, etc.)
- Container tests (iterable, mapping, etc.)
- Proper signature extraction and alias handling

.. jinja:nodes:: jinja2.nodes.Node

This recursively documents:
- Base Node class with common attributes
- All subclasses (Expr, Stmt, Template, etc.)
- Abstract methods for abstract classes
- Parent class references
- Class inheritance relationships

.. jinja:filters:: mypackage.filters.CUSTOM_FILTERS

Where mypackage.filters.py contains:

.. code-block:: python

   def my_filter(value, arg1, arg2="default"):
       """Custom filter that processes values."""
       return f"{value}-{arg1}-{arg2}"
   
   CUSTOM_FILTERS = {
       'my_filter': my_filter,
       'custom': my_filter,  # alias
   }

.. jinja:tests:: mypackage.tests.CUSTOM_TESTS

Where mypackage.tests.py contains:

.. code-block:: python

   def is_valid_email(value):
       """Test if value is a valid email address."""
       import re
       pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
       return re.match(pattern, value) is not None
   
   CUSTOM_TESTS = {
       'valid_email': is_valid_email,
       'email': is_valid_email,  # alias
   }

# Async filters are unwrapped to their sync variants for documentation
@jinja_async_variant
def async_my_filter(value):
    # This will be unwrapped to the sync version for signature extraction
    pass

# Context/environment filters have their first argument removed from docs
@jinja_pass_environment  
def env_filter(environment, value, arg):
    # Documented signature will be: env_filter(value, arg)
    pass

# Short comparison names are preferred as primary names
TESTS = {
    'eq': operator.eq,
    'equalto': operator.eq,  # 'eq' becomes primary, 'equalto' is alias
}