!!! warning "This is the documentation for the NEW, EXPERIMENTAL Python handler." To read the documentation for the LEGACY handler, go to the legacy handler documentation.

Like every handler, the Python handler accepts the common selection and rendering options, both as global and local options. The selection options gives you control over the selection of Python objects, while the rendering options lets you change how the documentation is rendered.

The following options are directly passed to the handler's collector. See Collector: Griffe to learn more about Griffe.

!!! example "Configuration example" === "Global" yaml # mkdocs.yml plugins: - mkdocstrings: handlers: python: selection: docstring_style: google

=== "Local"
    ```yaml
    ::: my_package
        selection:
          docstring_style: sphinx
    ```

::: mkdocstrings_handlers.python.renderer.PythonRenderer.default_config rendering: show_root_toc_entry: false

These options affect how the documentation is rendered.

!!! example "Configuration example" === "Global" yaml # mkdocs.yml plugins: - mkdocstrings: handlers: python: rendering: show_root_heading: yes

=== "Local"
    ```md
    ## `ClassA`

    ::: my_package.my_module.ClassA
        rendering:
          show_root_heading: no
          heading_level: 3
    ```

The tool used by the Python handler to collect documentation from Python source code is Griffe. Griffe can mean "signature" in french.

Griffe supports the Google-style, Numpy-style and Sphinx-style docstring formats. The style used by default is the Google-style. You can configure what style you want to use with the docstring_style and docstring_options selection options, both globally or per autodoc instruction.

• Google: see Napoleon's documentation.
• Numpy: see Numpydoc's documentation.
• Sphinx: see Sphinx's documentation.

See the supported docstring sections on Griffe's documentation.

!!! note As Numpy-style is partially supported by the underlying parser, you may experience problems in the building process if your docstring has a Methods section in the class docstring (see #366).

With Google-style docstrings, any section that is not recognized will be transformed into its admonition equivalent. For example:

=== "Docstring" ```python """ Important: It looks like a section, but it will be rendered as an admonition.

Tip: You can even chose a title.
    This admonition has a custom title!
"""
```

=== "Result" !!! important It looks like a section, but it will be rendered as an admonition.

!!! tip "You can even chose a title."
    This admonition has a custom title!

In order for Griffe to find your packages and modules, you can take advantage of the usual Python loading mechanisms:

• install your package in the current virtualenv:

  . venv/bin/activate
  pip install -e .

  poetry install

  ...etc.

• or add your package(s) parent directory in the PYTHONPATH.

(The following instructions assume your Python package is in the src directory.)

In Bash and other shells, you can run your command like this (note the prepended PYTHONPATH=...):

$ PYTHONPATH=src mkdocs serve

You can also export that variable, but this is not recommended as it could affect other Python processes:

export PYTHONPATH=src  # Linux/Bash and similar
setx PYTHONPATH src  # Windows, USE AT YOUR OWN RISKS

Here are some CSS rules for the Material for MkDocs theme:

/* Indentation. */
div.doc-contents:not(.first) {
  padding-left: 25px;
  border-left: .05rem solid var(--md-default-fg-color--lightest);
  margin-bottom: 80px;
}

Here are some CSS rules for the built-in ReadTheDocs theme:

/* Indentation. */
div.doc-contents:not(.first) {
  padding-left: 25px;
  border-left: .05rem solid rgba(200, 200, 200, 0.2);
  margin-bottom: 60px;
}