tessl/pypi-mkdocstrings-python

A Python handler for mkdocstrings that generates API documentation from source code using Griffe.

—

Pending

Overview

Eval results

Files

Handler and Core Functionality

Name: tessl/pypi-mkdocstrings-python
Author: tessl

Core components for creating and using the mkdocstrings-python handler to collect and render Python API documentation.

Capabilities

Handler Creation

Factory function to create a configured PythonHandler instance with specified options and base directory.

def get_handler(
    handler_config: dict[str, Any],
    tool_config: object,
    **kwargs
) -> PythonHandler:
    """
    Return an instance of PythonHandler.
    
    Parameters:
    - handler_config: dict[str, Any] - The handler configuration dictionary
    - tool_config: object - The tool (SSG) configuration
    - **kwargs: Additional arguments to pass to the handler
    
    Returns:
    PythonHandler - An instance of PythonHandler
    """

Usage Example:

from mkdocstrings_handlers.python import get_handler
from pathlib import Path

# Create handler configuration dictionary
handler_config = {
    "docstring_style": "google",
    "show_source": True,
    "show_root_heading": True,
    "members_order": "alphabetical"
}

# Mock tool config (normally provided by mkdocstrings)
tool_config = type('Config', (), {'config_file_path': 'mkdocs.yml'})()

# Get handler instance
handler = get_handler(handler_config=handler_config, tool_config=tool_config)

Handler Class

Main handler class that extends BaseHandler and provides Python-specific documentation collection and rendering functionality.

class PythonHandler(BaseHandler):
    """The Python handler class for mkdocstrings."""
    
    name: str = "python"
    domain: str = "py" 
    enable_inventory: bool = True
    fallback_theme: str = "material"
    
    def __init__(
        self,
        config: PythonConfig,
        base_dir: Path,
        **kwargs
    ) -> None:
        """
        Initialize the handler.
        
        Parameters:
        - config: PythonConfig - Handler configuration
        - base_dir: Path - Base directory of the project
        - **kwargs: Arguments passed to parent constructor
        """
        
    def collect(
        self,
        identifier: str,
        options: PythonOptions
    ) -> CollectorItem:
        """
        Collect the documentation for the given identifier.
        
        Parameters:
        - identifier: str - The identifier of the object to collect
        - options: PythonOptions - The options to use for the collection
        
        Returns:
        CollectorItem - The collected item
        
        Raises:
        CollectionError - If the object cannot be found or collected
        """
        
    def get_options(
        self,
        local_options: dict[str, Any]
    ) -> HandlerOptions:
        """
        Get handler options by merging local and global configurations.
        
        Parameters:
        - local_options: dict[str, Any] - Local configuration options
        
        Returns:
        HandlerOptions - Merged handler options
        """
        
    def get_inventory_urls(self) -> list[tuple[str, dict[str, Any]]]:
        """
        Get inventory URLs for cross-reference resolution.
        
        Returns:
        list[tuple[str, dict[str, Any]]] - List of inventory URLs and their metadata
        """
        
    def render(
        self,
        data: CollectorItem,
        options: PythonOptions,
        locale: str | None = None
    ) -> str:
        """
        Render the collected data.
        
        Parameters:
        - data: CollectorItem - The collected data
        - options: PythonOptions - The options to use for rendering
        - locale: str | None - The locale to use for rendering (default is "en")
        
        Returns:
        str - The rendered data (HTML)
        """
        
    def teardown(self) -> None:
        """Clean up handler resources."""
        
    def update_env(
        self,
        md: object,
        config: dict
    ) -> None:
        """Update the Jinja2 environment with handler-specific functions."""

Usage Example:

from mkdocstrings_handlers.python import PythonHandler, PythonConfig
from pathlib import Path

# Create handler directly
handler = PythonHandler(
    config=PythonConfig(),
    base_dir=Path.cwd()
)

# Collect documentation for a module
from mkdocstrings_handlers.python import PythonOptions
options = PythonOptions(docstring_style="google")
data = handler.collect("numpy.array", options)

# Render the documentation
html = handler.render(data, options, locale="en")

Error Handling

The handler raises specific exceptions for different error conditions:

CollectionError: When a Python object cannot be found or analyzed
PluginError: For configuration or setup issues
AliasResolutionError: When cross-references cannot be resolved
TemplateNotFound: When required Jinja2 templates are missing

Example Error Handling:

from mkdocstrings import CollectionError
from mkdocs.exceptions import PluginError

try:
    data = handler.collect("nonexistent.module", {})
except CollectionError as e:
    print(f"Failed to collect documentation: {e}")
except PluginError as e:
    print(f"Configuration error: {e}")

Install with Tessl CLI

npx tessl i tessl/pypi-mkdocstrings-python

docs