mkdocstrings-python

What it is and what it does

mkdocstrings-python is a handler that extends mkdocstrings to automatically generate API documentation from Python source code. It uses griffelib to parse the Abstract Syntax Tree (AST) of your code, extract docstrings, and collect type annotations, then renders them as searchable HTML documentation integrated into your MkDocs site.

The handler supports multiple docstring styles, automatically generates cross-references to other objects in your API, and can display source code inline. You reference Python modules by their dotted path in your documentation, and the handler recursively documents all classes, functions, and attributes without requiring manual entries for each one.

Use it for:

• Generate complete API reference documentation for a Python library automatically from docstrings and type hints.
• Create searchable, cross-referenced documentation that links parameter types to their definitions across your codebase.
• Build documentation sites that stay in sync with source code changes without manual updates to API docs.
• Display inline source code for functions and classes alongside their documentation for developer reference.
• Support teams maintaining multiple Python packages by reusing the same documentation pipeline across projects.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Generates API documentation for Python projects by parsing source code and docstrings, integrating with mkdocstrings to produce searchable, cross-referenced documentation.

Yes. The package is actively maintained, has low install friction, carries a permissive ISC license, and solves a real problem—keeping API documentation synchronized with source code. It has no known vulnerabilities and is well-positioned in the top 5000 PyPI packages. Install it if you use mkdocstrings and want to document Python code automatically.

Install

mkdocstrings-python on PyPI

pip install mkdocstrings-python

uv add mkdocstrings-python

poetry add mkdocstrings-python

Installing mkdocstrings-python

Before you install

Low friction install with 4 runtime dependencies; actively maintained with recent release (56 days ago) and ongoing commits.

License in practice

ISC license is permissive, allowing use in proprietary and open-source projects with minimal restrictions.

Quickstart

pip install mkdocstrings-python

import mkdocstrings
# In mkdocs.yml, configure the Python handler and reference modules by dotted path:
# ::: mypackage.mymodule

Requires Python 3.10 or later; mkdocstrings must be installed and configured in your MkDocs project.

Verify before relying

• Performance characteristics when documenting very large Python codebases with hundreds of modules.
• Compatibility with popular MkDocs themes and recent versions of mkdocs-autorefs.
• Whether all three docstring styles (Google, NumPy, Sphinx) are equally well supported or have known limitations.

Package facts

Evidence: mkdocstrings_python-2.0.5-py3-none-any.whl

Tags

More Software Development packages