or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdhandler-core.mdindex.mdrendering.md
tile.json

tessl/pypi-mkdocstrings-python

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/mkdocstrings-python@1.18.x

To install, run

npx @tessl/cli install tessl/pypi-mkdocstrings-python@1.18.0

index.mddocs/

mkdocstrings-python

A Python handler for mkdocstrings that generates comprehensive API documentation from Python source code. Using the Griffe library for Abstract Syntax Tree analysis and runtime introspection, it automatically extracts documentation from Python modules, classes, functions, and type annotations while supporting multiple docstring formats and providing extensive customization options.

Package Information

  • Package Name: mkdocstrings-python
  • Language: Python
  • Installation: pip install mkdocstrings-python or pip install mkdocstrings[python]

Core Imports

from mkdocstrings_handlers.python import PythonHandler, get_handler

Common configuration imports:

from mkdocstrings_handlers.python import (
    PythonConfig,
    PythonOptions,
    GoogleStyleOptions,
    NumpyStyleOptions,  
    SphinxStyleOptions
)

Basic Usage

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

# Get a configured handler instance
handler = get_handler(
    config=PythonConfig(
        options={
            "show_source": True,
            "show_root_heading": True,
            "docstring_style": "google"
        }
    ),
    base_dir=Path.cwd()
)

# Use the handler to collect documentation for a Python module
data = handler.collect("my_module", {})

# Render the documentation 
rendered = handler.render(data, {})

Architecture

The mkdocstrings-python handler follows a modular architecture:

  • Handler: Core PythonHandler class that orchestrates documentation collection and rendering
  • Configuration: Comprehensive options system supporting multiple docstring styles and rendering preferences
  • Rendering: Template-based rendering system with extensive formatting and cross-referencing capabilities
  • Integration: Seamless integration with mkdocstrings ecosystem and MkDocs Material theme

The handler leverages Griffe for robust Python code analysis, supporting both static AST analysis and runtime introspection when source code is unavailable.

Capabilities

Handler and Core Functionality

Primary handler class and factory function for creating configured instances that orchestrate the documentation generation process.

class PythonHandler(BaseHandler):
    def __init__(self, config: PythonConfig, base_dir: Path, **kwargs): ...
    def collect(self, identifier: str, config: dict) -> CollectorItem: ...
    def render(self, data: CollectorItem, config: dict) -> str: ...

def get_handler(config: PythonConfig, base_dir: Path, **kwargs) -> PythonHandler: ...

Handler and Core Functionality

Configuration Options

Comprehensive configuration system supporting multiple docstring styles, rendering preferences, and handler behavior customization.

class PythonConfig:
    options: PythonOptions

class PythonOptions:
    docstring_style: str = "google"
    show_source: bool = False
    show_root_heading: bool = False
    heading_level: int = 1
    members_order: Order = "alphabetical"
    filters: list[str] = field(default_factory=lambda: [])
    # ... many more options

class GoogleStyleOptions:
    ignore_init_summary: bool = False
    returns_multiple_items: bool = True
    returns_named_value: bool = True
    # ... additional Google-style options

class NumpyStyleOptions:
    returns_multiple_items: bool = True
    returns_named_value: bool = True
    # ... additional NumPy-style options

class SphinxStyleOptions:
    returns_multiple_items: bool = True
    returns_named_value: bool = True  
    # ... additional Sphinx-style options

Configuration Options

Rendering and Template Functions

Template functions and utilities for formatting code signatures, handling cross-references, and organizing documentation output.

def do_format_signature(signature: str, line_length: int = 60) -> str: ...
def do_format_code(code: str, line_length: int = 88) -> str: ...
def do_crossref(path: str, *, brief: bool = True) -> str: ...
def do_filter_objects(objects: list, filters: list[str]) -> list: ...
def do_order_members(members: list, order: Order) -> list: ...

class AutorefsHook:
    def on_collect(self, env: dict) -> None: ...
    def on_config(self, config: dict) -> None: ...

Rendering and Template Functions

Types

Order = Literal["__all__", "alphabetical", "source"]
"""Ordering methods for object members."""

Tree = dict[tuple[str, ...], "Tree"]
"""Tree data structure for organizing hierarchical documentation as nested dictionaries."""

class Inventory:
    """Configuration for cross-reference inventories."""
    base_url: str
    
class SummaryOption:
    """Options for docstring summary handling."""

Markup = str
"""Safe HTML markup type from markupsafe library."""