mkdocstrings-python

mkdocstrings-python is the official Python handler for mkdocstrings, the plugin that injects auto-generated API documentation into MkDocs sites. It uses Griffe to collect information from Python source code - visiting the AST or introspecting imported objects - and to parse docstrings written in Google, NumPy, or Sphinx styles.

With it, you reference a Python object in your Markdown and get richly rendered signatures, parameters, attributes, and docstring content, keeping your documentation in sync with your codebase without manual duplication.

What You Get

• Automatic API documentation rendered from Python source code
• Griffe-powered collection via AST parsing or runtime introspection
• Support for Google, NumPy, and Sphinx docstring styles
• Configurable rendering options for signatures, members, and headings
• Cross-references between documented objects across your project

Common Use Cases

• Generating API reference pages for a Python library in MkDocs
• Keeping documentation in sync with code by pulling from docstrings
• Rendering class and function signatures with typed parameters
• Building a documentation site with Material for MkDocs and autodoc

Under The Hood

Architecture - mkdocstrings-python implements the handler interface expected by mkdocstrings, living under src/mkdocstrings_handlers/python. When mkdocstrings encounters an identifier reference, it invokes this handler’s collect step, which delegates to Griffe to build an object tree from the target module (via AST visitation or runtime import/introspection), then renders it through Jinja templates into HTML for the docs page, honoring per-object configuration options. Tech Stack - Pure Python packaged with modern PEP 621 metadata in pyproject.toml, built around Griffe for collection and MkDocs/mkdocstrings for the rendering pipeline, with Jinja templates and Material-friendly CSS. Tooling includes a Makefile, duties.py task runner, and a full docs site. Code Quality - The project has a dedicated tests/ suite, CI via GitHub Actions, a maintained CHANGELOG, and code-of-conduct/contributing docs, reflecting an actively developed, mature codebase with good engineering hygiene. API Design - End users interact through YAML configuration options and Markdown identifier references rather than Python calls, and the extensive, well-documented option set gives fine control over rendering; the breadth of options adds some learning curve, but defaults produce usable output immediately.