or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

handler-system.md index.md inventory-system.md logging-system.md markdown-processing.md plugin-integration.md rendering-system.md

tile.json

tessl/pypi-mkdocstrings

Automatic documentation from sources, for MkDocs.

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:pypi/mkdocstrings@0.30.x

To install, run

npx @tessl/cli install tessl/pypi-mkdocstrings@0.30.0

mkdocstrings

A language-agnostic documentation generation system for MkDocs that automatically extracts and renders documentation from source code. mkdocstrings enables developers to embed API documentation directly into their Markdown files using a simple ::: identifier syntax, supports multiple programming languages through extensible handlers, and offers cross-referencing capabilities both within projects and across external libraries.

Package Information

Package Name: mkdocstrings
Package Type: pypi
Language: Python
Installation: pip install mkdocstrings

Core Imports

import mkdocstrings

For MkDocs plugin configuration:

# mkdocs.yml
plugins:
  - mkdocstrings

For direct extension usage:

from mkdocstrings import MkdocstringsExtension, BaseHandler, Handlers

Basic Usage

As MkDocs Plugin

Install mkdocstrings:

pip install mkdocstrings

Configure in mkdocs.yml:

plugins:
  - mkdocstrings:
      handlers:
        python:
          options:
            docstring_style: google

Use in Markdown files:

# My API Documentation

::: my_module.MyClass
    options:
      show_source: false
      
::: my_module.my_function

Direct Extension Usage

from markdown import Markdown
from mkdocstrings import MkdocstringsExtension, Handlers

# Create handlers instance
handlers = Handlers(
    theme="material",
    default="python",
    inventory_project="my-project"
)

# Create and configure Markdown instance
md = Markdown(extensions=[
    MkdocstringsExtension(handlers=handlers, autorefs=None)
])

# Process markdown with autodoc blocks
result = md.convert("""
::: my_module.MyClass
    options:
      show_source: false
""")

Architecture

mkdocstrings follows a modular architecture centered around handlers and processors:

Plugin System: MkdocstringsPlugin integrates with MkDocs build process
Extension System: MkdocstringsExtension and AutoDocProcessor process ::: identifier blocks in Markdown
Handler System: BaseHandler and Handlers provide language-specific documentation extraction
Inventory System: Inventory and InventoryItem enable cross-project documentation linking
Rendering System: Tree processors and highlighters format the final output
Logging System: Specialized loggers for templates and debugging

This modular design enables extensibility through custom handlers while maintaining consistent processing and rendering across different programming languages.

Capabilities

Plugin Integration

Core MkDocs plugin functionality for seamless integration with MkDocs sites, including configuration management, build process integration, and theme support.

class MkdocstringsPlugin(BasePlugin[PluginConfig]):
    def on_config(self, config: MkDocsConfig) -> MkDocsConfig | None: ...
    def on_post_build(self, config: MkDocsConfig, **kwargs: Any) -> None: ...
    def get_handler(self, handler_name: str) -> BaseHandler: ...

class PluginConfig(Config):
    handlers = opt.Type(dict, default={})
    default_handler = opt.Type(str, default="python")
    custom_templates = opt.Optional(opt.Dir(exists=True))
    enable_inventory = opt.Optional(opt.Type(bool))
    enabled = opt.Type(bool, default=True)
    locale = opt.Optional(opt.Type(str))

Plugin Integration

Handler System

Extensible handler system for processing different programming languages, with base classes for creating custom handlers and a manager for handler lifecycle.

class BaseHandler:
    name: ClassVar[str] = ""
    domain: ClassVar[str] = ""
    enable_inventory: ClassVar[bool] = False
    
    def collect(self, identifier: str, options: HandlerOptions) -> CollectorItem: ...
    def render(self, data: CollectorItem, options: HandlerOptions, *, locale: str | None = None) -> str: ...

class Handlers:
    def __init__(self, *, theme: str, default: str, inventory_project: str, ...): ...
    def get_handler(self, name: str, handler_config: dict | None = None) -> BaseHandler: ...

Handler System

Markdown Processing

Markdown extension and processors for parsing and rendering ::: identifier autodoc blocks within Markdown documents.

class MkdocstringsExtension(Extension):
    def __init__(self, handlers: Handlers, autorefs: AutorefsPlugin, **kwargs: Any) -> None: ...
    def extendMarkdown(self, md: Markdown) -> None: ...

class AutoDocProcessor(BlockProcessor):
    def test(self, parent: Element, block: str) -> bool: ...
    def run(self, parent: Element, blocks: MutableSequence[str]) -> None: ...

Markdown Processing

Inventory and Cross-Referencing

Object inventory system for managing and cross-referencing documentation objects within and across projects.

class Inventory(dict):
    def __init__(self, items: list[InventoryItem] | None = None, project: str = "project", version: str = "0.0.0") -> None: ...
    def register(self, name: str, domain: str, role: str, uri: str, priority: int = 1, dispname: str | None = None) -> None: ...
    def format_sphinx(self) -> bytes: ...

class InventoryItem:
    def __init__(self, name: str, domain: str, role: str, uri: str, priority: int = 1, dispname: str | None = None) -> None: ...

Inventory System

Rendering and Formatting

HTML rendering components including syntax highlighting, heading management, and output formatting processors.

class Highlighter(Highlight):
    def highlight(self, src: str, language: str | None = None, *, inline: bool = False, dedent: bool = True, linenums: bool | None = None, **kwargs: Any) -> str: ...

class HeadingShiftingTreeprocessor(Treeprocessor):
    def __init__(self, md: Markdown, shift_by: int) -> None: ...
    def run(self, root: Element) -> None: ...

Rendering System

Logging and Debugging

Specialized logging system designed for template environments and debugging mkdocstrings processing.

class LoggerAdapter(logging.LoggerAdapter):
    def __init__(self, prefix: str, logger: logging.Logger) -> None: ...

class TemplateLogger:
    def __init__(self, logger: LoggerAdapter) -> None: ...

def get_logger(name: str) -> LoggerAdapter: ...
def get_template_logger(handler_name: str | None = None) -> TemplateLogger: ...

Logging System

Types

Core Types

CollectorItem = Any  # Type of item returned by handler's collect method
HandlerConfig = Any  # Type for handler configuration
HandlerOptions = Any  # Type for options passed to handlers

Exception Types

class CollectionError(Exception):
    """Raised when data collection fails."""

class ThemeNotSupported(Exception):
    """Raised when a theme is not supported."""

Constants

TEMPLATES_DIRS: Sequence[Path]  # Directories where handler templates are located

Utility Functions

def do_any(seq: Sequence, attribute: str | None = None) -> bool:
    """Check if any item in sequence evaluates to True (Jinja filter)."""

def get_template_path(context: Context) -> str:
    """Return path to template using given context."""

def get_template_logger_function(logger_func: Callable) -> Callable:
    """Create wrapper function for template logging."""

Version

Tile

Files

tessl/pypi-mkdocstrings

To install, run

index.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

mkdocstrings

Package Information

Core Imports

Basic Usage

As MkDocs Plugin

Direct Extension Usage

Architecture

Capabilities

Plugin Integration

Handler System

Markdown Processing

Inventory and Cross-Referencing

Rendering and Formatting

Logging and Debugging

Types

Core Types

Exception Types

Constants

Utility Functions

index.mddocs/