Usage¤

This is the documentation for the NEW Python handler.

To read the documentation for the LEGACY handler, go to the legacy handler documentation.

Installation¤

You can install this handler as a mkdocstrings extra:

pyproject.toml

# PEP 621 dependencies declaration
# adapt to your dependencies manager
[project]
dependencies = [
    "mkdocstrings[python]>=0.18",
]

You can also explicitly depend on the handler:

pyproject.toml

# PEP 621 dependencies declaration
# adapt to your dependencies manager
[project]
dependencies = [
    "mkdocstrings-python",
]

The Python handler is the default mkdocstrings handler. You can change the default handler, or explicitely set the Python handler as default by defining the default_handler configuration option of mkdocstrings in mkdocs.yml:

mkdocs.yml

plugins:
- mkdocstrings:
    default_handler: python

Injecting documentation¤

With the Python handler installed and configured as default handler, you can inject documentation for a module, class, function, or any other Python object with mkdocstrings' autodoc syntax, in your Markdown pages:

::: path.to.object

If another handler was defined as default handler, you can explicitely ask for the Python handler to be used when injecting documentation with the handler option:

::: path.to.object
    handler: python

Configuration¤

When installed, the Python handler becomes the default mkdocstrings handler. You can configure it in mkdocs.yml:

mkdocs.yml

plugins:
- mkdocstrings:
    handlers:
      python:
        ...  # the Python handler configuration

Global-only options¤

Some options are global only, and go directly under the handler's name.

`import`¤

This option is used to import Sphinx-compatible objects inventories from other documentation sites. For example, you can import the standard library objects inventory like this:

mkdocs.yml

plugins:
- mkdocstrings:
    handlers:
      python:
        import:
        - https://docs.python-requests.org/en/master/objects.inv

When importing an inventory, you enable automatic cross-references to other documentation sites like the standard library docs or any third-party package docs. Typically, you want to import the inventories of your project's dependencies, at least those that are used in the public API.

See mkdocstrings' documentation on inventories for more details.

Additionally, the Python handler accepts a domains option in the import items, which allows to select the inventory domains to select. By default the Python handler only selects the py domain (for Python objects). You might find useful to also enable the std domain:

mkdocs.yml

plugins:
- mkdocstrings:
    handlers:
      python:
        import:
        - url: https://docs.python-requests.org/en/master/objects.inv
          domains: [std, py]

Note

The import option is common to all handlers, however they might implement it differently, or not even implement it.

`paths`¤

This option is used to provide filesystem paths in which to search for Python modules. Non-absolute paths are computed as relative to MkDocs configuration file. Example:

mkdocs.yml

plugins:
- mkdocstrings:
    handlers:
      python:
        paths: [src]  # search packages in the src folder

More details at Finding modules.

`load_external_modules`¤

This option allows resolving aliases (imports) to any external module. Modules are considered external when they are not part of the package your are injecting documentation for. Setting this option to True will tell the handler to resolve aliases recursively when they are made public through the __all__ variable. By default, the handler will only resolve aliases when they point at a private sibling of the source package, for example aliases going from ast to _ast. Set load_external_modules to False to prevent even that.

Use with caution

This can load a lot of modules through Griffe, slowing down your build or triggering errors that Griffe does not yet handle. We recommend using the preload_modules option instead, which acts as an include-list rather than as include-all.

Example:

mkdocs.yml

plugins:
- mkdocstrings:
    handlers:
      python:
        load_external_modules: true

Global/local options¤

The other options can be used both globally and locally, under the options key. For example, globally:

mkdocs.yml

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          do_something: true

...and locally, overriding the global configuration:

docs/some_page.md

::: package.module.class
    options:
      do_something: false

These options affect how the documentation is collected from sources and rendered. See the following tables summarizing the options, and get more details for each option in the following pages:

General options: various options that do not fit in the other categories
Headings options: options related to headings and the table of contents (or sidebar, depending on the theme used)
Members options: options related to filtering or ordering members in the generated documentation
Docstrings options: options related to docstrings (parsing and rendering)
Signature options: options related to signatures and type annotations

Options summary¤

Default handler configuration.

General options:

find_stubs_package (bool) –

Whether to load stubs package (package-stubs) when extracting docstrings. Default False.
allow_inspection (bool) –

Whether to allow inspecting modules when visiting them is not possible. Default: True.
show_bases (bool) –

Show the base classes of a class. Default: True.
show_inheritance_diagram (bool) –

Show the inheritance diagram of a class using Mermaid. Default: False.
show_source (bool) –

Show the source code of this object. Default: True.
preload_modules (list[str] | None) –

Pre-load modules that are not specified directly in autodoc instructions (::: identifier). It is useful when you want to render documentation for a particular member of an object, and this member is imported from another package than its parent.

For an imported member to be rendered, you need to add it to the __all__ attribute of the importing module.

The modules must be listed as an array of strings. Default: None.

Headings options:

heading_level (int) –

The initial heading level to use. Default: 2.
parameter_headings (bool) –

Whether to render headings for parameters (therefore showing parameters in the ToC). Default: False.
show_root_heading (bool) –

Show the heading of the object at the root of the documentation tree (i.e. the object referenced by the identifier after :::). Default: False.
show_root_toc_entry (bool) –

If the root heading is not shown, at least add a ToC entry for it. Default: True.
show_root_full_path (bool) –

Show the full Python path for the root object heading. Default: True.
show_root_members_full_path (bool) –

Show the full Python path of the root members. Default: False.
show_object_full_path (bool) –

Show the full Python path of every object. Default: False.
show_category_heading (bool) –

When grouped by categories, show a heading for each category. Default: False.
show_symbol_type_heading (bool) –

Show the symbol type in headings (e.g. mod, class, meth, func and attr). Default: False.
show_symbol_type_toc (bool) –

Show the symbol type in the Table of Contents (e.g. mod, class, methd, func and attr). Default: False.

Members options:

inherited_members (list[str] | bool | None) –

A boolean, or an explicit list of inherited members to render. If true, select all inherited members, which can then be filtered with members. If false or empty list, do not select any inherited member. Default: False.
members (list[str] | bool | None) –

A boolean, or an explicit list of members to render. If true, select all members without further filtering. If false or empty list, do not render members. If none, select all members and apply further filtering with filters and docstrings. Default: None.
members_order (str) –

The members ordering to use. Options: alphabetical - order by the members names, source - order members as they appear in the source file. Default: "alphabetical".
filters (list[str] | None) –

A list of filters applied to filter objects based on their name. A filter starting with ! will exclude matching objects instead of including them. The members option takes precedence over filters (filters will still be applied recursively to lower members in the hierarchy). Default: ["!^_[^_]"].
group_by_category (bool) –

Group the object's children by categories: attributes, classes, functions, and modules. Default: True.
show_submodules (bool) –

When rendering a module, show its submodules recursively. Default: False.
summary (bool | dict[str, bool]) –

Whether to render summaries of modules, classes, functions (methods) and attributes.
show_labels (bool) –

Whether to show labels of the members. Default: True.

Docstrings options:

docstring_style (str) –

The docstring style to use: google, numpy, sphinx, or None. Default: "google".
docstring_options (dict) –

The options for the docstring parser. See docstring parsers and their options in Griffe docs.
docstring_section_style (str) –

The style used to render docstring sections. Options: table, list, spacy. Default: "table".
merge_init_into_class (bool) –

Whether to merge the __init__ method into the class' signature and docstring. Default: False.
relative_crossrefs (bool) –

Whether to enable the relative crossref syntax. Default: False.
scoped_crossrefs (bool) –

Whether to enable the scoped crossref ability. Default: False.
show_if_no_docstring (bool) –

Show the object heading even if it has no docstring or children with docstrings. Default: False.
show_docstring_attributes (bool) –

Whether to display the "Attributes" section in the object's docstring. Default: True.
show_docstring_functions (bool) –

Whether to display the "Functions" or "Methods" sections in the object's docstring. Default: True.
show_docstring_classes (bool) –

Whether to display the "Classes" section in the object's docstring. Default: True.
show_docstring_modules (bool) –

Whether to display the "Modules" section in the object's docstring. Default: True.
show_docstring_description (bool) –

Whether to display the textual block (including admonitions) in the object's docstring. Default: True.
show_docstring_examples (bool) –

Whether to display the "Examples" section in the object's docstring. Default: True.
show_docstring_other_parameters (bool) –

Whether to display the "Other Parameters" section in the object's docstring. Default: True.
show_docstring_parameters (bool) –

Whether to display the "Parameters" section in the object's docstring. Default: True.
show_docstring_raises (bool) –

Whether to display the "Raises" section in the object's docstring. Default: True.
show_docstring_receives (bool) –

Whether to display the "Receives" section in the object's docstring. Default: True.
show_docstring_returns (bool) –

Whether to display the "Returns" section in the object's docstring. Default: True.
show_docstring_warns (bool) –

Whether to display the "Warns" section in the object's docstring. Default: True.
show_docstring_yields (bool) –

Whether to display the "Yields" section in the object's docstring. Default: True.

Signatures/annotations options:

annotations_path (str) –

The verbosity for annotations path: brief (recommended), or source (as written in the source). Default: "brief".
line_length (int) –

Maximum line length when formatting code/signatures. Default: 60.
show_signature (bool) –

Show methods and functions signatures. Default: True.
show_signature_annotations (bool) –

Show the type annotations in methods and functions signatures. Default: False.
signature_crossrefs (bool) –

Whether to render cross-references for type annotations in signatures. Default: False.
separate_signature (bool) –

Whether to put the whole signature in a code block below the heading. If Black is installed, the signature is also formatted using it. Default: False.
unwrap_annotated (bool) –

Whether to unwrap Annotated types to show only the type without the annotations. Default: False.
modernize_annotations (bool) –

Whether to modernize annotations, for example Optional[str] into str | None. Default: False.

Finding modules¤

There are multiple ways to tell the handler where to find your packages/modules.

The recommended method is to use the paths option, as it's the only one that works with the -f option of MkDocs, allowing to build the documentation from any location on the file system. Indeed, the paths provided with the paths option are computed as relative to the configuration file (mkdocs.yml), so that the current working directory has no impact on the build process: you can build the docs from any location on your filesystem.

Using the `paths` option¤

This is the recommended method.

mkdocs.yml in root, package in root

📁 root/
├──  mkdocs.yml
└── 📁 package/

mkdocs.yml

plugins:
- mkdocstrings:
    handlers:
      python:
        paths: [.]  # actually not needed, default

mkdocs.yml in root, package in subfolder

📁 root/
├──  mkdocs.yml
└── 📁 src/
    └── 📁 package/

mkdocs.yml

plugins:
- mkdocstrings:
    handlers:
      python:
        paths: [src]

mkdocs.yml in subfolder, package in root

📁 root/
├── 📁 docs/
│   └──  mkdocs.yml
└── 📁 package/

mkdocs.yml

plugins:
- mkdocstrings:
    handlers:
      python:
        paths: [..]

mkdocs.yml in subfolder, package in subfolder

📁 root/
├── 📁 docs/
│   └──  mkdocs.yml
└── 📁 src/
    └── 📁 package/

mkdocs.yml

plugins:
- mkdocstrings:
    handlers:
      python:
        paths: [../src]

Except for case 1, which is supported by default, we strongly recommend setting the path to your packages using this option, even if it works without it (for example because your project manager automatically adds src to PYTHONPATH), to make sure anyone can build your docs from any location on their filesystem.

Using the PYTHONPATH environment variable¤

This method has limitations.

This method might work for you, with your current setup, but not for others trying your build your docs with their own setup/environment. We recommend using the paths method instead.

You can take advantage of the usual Python loading mechanisms. In Bash and other shells, you can run your command like this (note the prepended PYTHONPATH=...):

mkdocs.yml in root, package in root

📁 root/
├──  mkdocs.yml
└── 📁 package/

PYTHONPATH=. mkdocs build  # actually not needed, default

mkdocs.yml in root, package in subfolder

📁 root/
├──  mkdocs.yml
└── 📁 src/
    └── 📁 package/

PYTHONPATH=src mkdocs build

mkdocs.yml in subfolder, package in root

📁 root/
├── 📁 docs/
│   └──  mkdocs.yml
└── 📁 package/

PYTHONPATH=. mkdocs build -f docs/mkdocs.yml

mkdocs.yml in subfolder, package in subfolder

📁 root/
├── 📁 docs/
│   └──  mkdocs.yml
└── 📁 src/
    └── 📁 package/

PYTHONPATH=src mkdocs build -f docs/mkdocs.yml

Installing your package in the current Python environment¤

This method has limitations.

This method might work for you, with your current setup, but not for others trying your build your docs with their own setup/environment. We recommend using the paths method instead.

Install your package in the current environment, and run MkDocs:

pipPDMPoetry

. venv/bin/activate
pip install -e .
mkdocs build

pdm install
pdm run mkdocs build

poetry install
poetry run mkdocs build

Usage¤

Installation¤

Injecting documentation¤

Configuration¤

Global-only options¤

import¤

paths¤

load_external_modules¤

Global/local options¤

Options summary¤

Finding modules¤

Using the paths option¤

Using the PYTHONPATH environment variable¤

Installing your package in the current Python environment¤

Feedback

`import`¤

`paths`¤

`load_external_modules`¤

Using the `paths` option¤