Skip to content

Latest commit

 

History

History
390 lines (307 loc) · 10.1 KB

index.md

File metadata and controls

390 lines (307 loc) · 10.1 KB

Usage

TIP: 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:

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

You can also explicitly depend on the handler:

# 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:

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

Internationalization (i18n)

The Python handler of mkdocstrings supports changing the output language.

The following languages can be used by enabling in mkdocstrings configuration:

Currently supported languages:

  • :flag_us: en: English (default)
  • :flag_cn: zh: Chinese (Simplified)
  • :flag_jp: ja: Japanese

Configuration

When installed, the Python handler becomes the default mkdocstrings handler. You can configure it in 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:

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:

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:

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. Enabling this option will tell the handler to resolve aliases recursively when they are made public through the __all__ variable.

WARNING: 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:

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:

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

...and locally, overriding the global configuration:

::: 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

::: mkdocstrings_handlers.python.handler.PythonHandler.default_config options: show_root_heading: false show_root_toc_entry: 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

TIP: This is the recommended method.

  1. mkdocs.yml in root, package in root

    root/
    mkdocs.yml
    package/

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

  2. mkdocs.yml in root, package in subfolder

    root/
    mkdocs.yml
    src/
        package/

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

  3. mkdocs.yml in subfolder, package in root

    root/
    docs/
        mkdocs.yml
    package/

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

  4. mkdocs.yml in subfolder, package in subfolder

    root/
    docs/
        mkdocs.yml
    src/
        package/

    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

WARNING: 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=...):

  1. mkdocs.yml in root, package in root

    root/
    mkdocs.yml
    package/

    PYTHONPATH=. mkdocs build  # actually not needed, default

  2. mkdocs.yml in root, package in subfolder

    root/
    mkdocs.yml
    src/
        package/

    PYTHONPATH=src mkdocs build

  3. mkdocs.yml in subfolder, package in root

    root/
    docs/
        mkdocs.yml
    package/

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

  4. 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

WARNING: 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:

/// tab | pip

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

///

/// tab | PDM

pdm install
pdm run mkdocs build

///

/// tab | Poetry

poetry install
poetry run mkdocs build

///