tessl/pypi-mkdocstrings

Automatic documentation from sources, for MkDocs.

—

Pending

Overview

Eval results

Files

Plugin Integration

Name: tessl/pypi-mkdocstrings
Author: tessl

Core MkDocs plugin functionality for seamless integration with MkDocs sites. The plugin system manages configuration, integrates with the MkDocs build process, and coordinates with themes and other plugins.

Capabilities

MkDocs Plugin

The main plugin class that integrates mkdocstrings into the MkDocs build pipeline.

class MkdocstringsPlugin(BasePlugin[PluginConfig]):
    """Main MkDocs plugin class for mkdocstrings."""
    
    def __init__(self) -> None:
        """Initialize the plugin."""
    
    def on_config(self, config: MkDocsConfig) -> MkDocsConfig | None:
        """Process MkDocs configuration and set up mkdocstrings."""
    
    on_env: CombinedEvent
    """Jinja2 environment event handler for template setup."""
    
    def on_post_build(self, config: MkDocsConfig, **kwargs: Any) -> None:
        """Post-build cleanup and finalization."""
    
    def get_handler(self, handler_name: str) -> BaseHandler:
        """Get a handler by name."""
    
    @property
    def handlers(self) -> Handlers:
        """Get the handlers instance."""
    
    @property
    def inventory_enabled(self) -> bool:
        """Whether inventory is enabled."""
    
    @property
    def plugin_enabled(self) -> bool:
        """Whether plugin is enabled."""
    
    css_filename: str = "assets/_mkdocstrings.css"

Usage Example:

# In MkDocs plugin context
from mkdocstrings import MkdocstringsPlugin

# Plugin is automatically instantiated by MkDocs
plugin = MkdocstringsPlugin()

# Get a specific handler
python_handler = plugin.get_handler("python")

# Check if inventory is enabled
if plugin.inventory_enabled:
    # Process inventory
    pass

Plugin Configuration

Configuration schema for the mkdocstrings plugin, defining all available options.

class PluginConfig(Config):
    """Configuration options for mkdocstrings plugin."""
    
    handlers = opt.Type(dict, default={})
    """Global handler configuration dict."""
    
    default_handler = opt.Type(str, default="python")
    """Default handler name to use when none specified."""
    
    custom_templates = opt.Optional(opt.Dir(exists=True))
    """Path to custom templates directory."""
    
    enable_inventory = opt.Optional(opt.Type(bool))
    """Enable/disable inventory creation."""
    
    enabled = opt.Type(bool, default=True)
    """Enable/disable the entire plugin."""
    
    locale = opt.Optional(opt.Type(str))
    """Locale for translations."""

Configuration Examples:

Basic configuration in mkdocs.yml:

plugins:
  - mkdocstrings

Advanced configuration:

plugins:
  - mkdocstrings:
      default_handler: python
      enable_inventory: true
      locale: en
      custom_templates: templates/
      handlers:
        python:
          options:
            docstring_style: google
            show_source: false
            show_root_heading: true
        javascript:
          options:
            show_source: true

Multi-language project configuration:

plugins:
  - mkdocstrings:
      default_handler: python
      handlers:
        python:
          paths: [src]
          options:
            docstring_style: google
            members_order: source
            show_signature_annotations: true
        javascript:
          options:
            show_source: false
            heading_level: 2

Integration Patterns

MkDocs Build Integration

The plugin integrates with key MkDocs build events:

Configuration Phase (on_config):
- Validates plugin configuration
- Sets up handlers with their configurations
- Prepares inventory settings
- Configures theme integration
Post-Build Phase (on_post_build):
- Cleans up temporary resources
- Finalizes inventory files
- Performs handler teardown

Theme Integration

mkdocstrings works with MkDocs themes by:

Injecting CSS for styling documentation blocks
Providing theme-specific templates for handlers
Supporting custom template directories
Adapting to theme-specific styling patterns

Handler Configuration

Handlers are configured through the plugin configuration:

# Plugin manages handler lifecycle
handlers_config = {
    "python": {
        "paths": ["src"],
        "options": {
            "docstring_style": "google",
            "show_source": False
        }
    }
}

# Handlers are instantiated and configured by the plugin
handlers = Handlers(
    theme=theme_name,
    default="python",
    handlers_config=handlers_config,
    inventory_project=project_name
)