General options¤

allow_inspection¤

• Type bool True

Whether to allow inspecting modules (importing them) when it is not possible to visit them (parse their source code).

When loading data for a given package, Griffe discovers every Python module, compiled or not, and inspects or visits them accordingly.

If you have compiled modules but also provide stubs for them, you might want to disable the inspection of these modules, because inspection picks up many more members, and sometimes the collected data is inaccurate (depending on the tool that was used to compile the module) or too low-level/technical for API documentation.

See also force_inspection.

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

::: path.to.object
    options:
      allow_inspection: false

backlinks¤

Sponsors only — Insiders 1.10.0

• Type Literal["flat", "tree", False] False

The backlinks option enables rendering of backlinks within your API documentation.

When an arbitrary section of your documentation links to an API symbol, this link will be collected as a backlink, and rendered below your API symbol. In short, the API symbol will link back to the section that links to it. Such backlinks will help your users navigate the documentation, as they will immediately which functions return a specific symbol, or where a specific symbol is accepted as parameter, etc..

Each backlink is a list of breadcrumbs that represent the navigation, from the root page down to the given section.

The available styles for rendering backlinks are flat and tree.

• flat will render backlinks as a single-layer list. This can lead to repetition of breadcrumbs.
• tree will combine backlinks into a tree, to remove repetition of breadcrumbs.

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          backlinks: tree

extensions¤

• Type list[str | dict[str, dict[str, Any]]] []

The extensions option lets you enable Griffe extensions, which enhance or modify the data collected from Python sources (or compiled modules).

Elements in the list can be strings or dictionaries.

Strings denote the path to an extension module, like griffe_typingdoc, or to an extension class directly, like griffe_typingdoc.TypingDocExtension. When using a module path, all extensions within that module will be loaded and enabled. Strings can also be the path to a Python module, and a class name separated with :, like scripts/griffe_extensions.py or scripts/griffe_extensions.py:MyExtension.

Dictionaries have a single key, which is the module/class path (as a dot-separated qualifier or file path and colon-separated class name, like above), and its value is another dictionary specifying options that will be passed when to class constructors when instantiating extensions.

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          extensions:
          - griffe_sphinx
          - griffe_pydantic: {schema: true}
          - scripts/exts.py:DynamicDocstrings:
              paths: [mypkg.mymod.myobj]

::: your_package.your_module.your_func
    options:
      extensions:
      - griffe_typingdoc

extra¤

• Type dict {}

The extra option lets you inject additional variables into the Jinja context used when rendering templates. You can then use this extra context in your overridden templates.

Local extra options will be merged into the global extra option:

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          extra:
            hello: world

::: your_package.your_module.your_func
    options:
      extra:
        foo: bar

...will inject both hello and foo into the Jinja context when rendering your_package.your_module.your_func.

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          hello: world

find_stubs_package¤

• Type bool False

When looking for documentation specified in autodoc instructions (::: identifier), also look for the stubs package as defined in PEP 561 if it exists. This is useful when most of your documentation is separately provided by such a package and not inline in your main package.

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

::: your_package.your_module.your_func
    options:
      find_stubs_package: true

def your_func(a, b):
    # Function code
    ...

# rest of your code

def your_func(a: int, b: str):
    """
    <Function docstring>
    """
    ...

# rest of your code

force_inspection¤

• Type bool False

Whether to force inspecting modules (importing them) even if their source code is available.

This option is useful when you know that dynamic analysis (inspection) yields better results than static analysis. Do not use this blindly: the recommended approach is to write a Griffe extension that will improve extracted API data. See How to selectively inspect objects.

See also allow_inspection.

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          force_inspection: false

::: path.to.object
    options:
      force_inspection: true

inheritance_diagram_direction¤

The direction of the Mermaid chart presenting the inheritance diagram of a class, TD by default.

extra_javascript:
- https://unpkg.com/mermaid@10.9.0/dist/mermaid.min.js

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          inheritance_diagram_direction: TD

::: path.to.object
    options:
      inheritance_diagram_direction: TD

class SuperAbstract:
    """Super abstract class."""
class Mixin1:
    """Mixin 1."""
class Abstract(SuperAbstract, Mixin1):
    """Abstract class."""
class Mixin2A:
    """Mixin 2A."""
class Mixin2B(Mixin2A):
    """Mixin 2B."""
class Concrete(Abstract, Mixin2B):
    """Concrete class."""
class SuperConcrete(Concrete):
    """Super concrete class."""

flowchart TD
SuperConcrete[SuperConcrete]
Concrete[Concrete]
Abstract[Abstract]
SuperAbstract[SuperAbstract]
Mixin1[Mixin1]
Mixin2B[Mixin2B]
Mixin2A[Mixin2A]

Concrete --> SuperConcrete
Abstract --> Concrete
SuperAbstract --> Abstract
Mixin1 --> Abstract
Mixin2B --> Concrete
Mixin2A --> Mixin2B

flowchart BT
SuperConcrete[SuperConcrete]
Concrete[Concrete]
Abstract[Abstract]
SuperAbstract[SuperAbstract]
Mixin1[Mixin1]
Mixin2B[Mixin2B]
Mixin2A[Mixin2A]

Concrete --> SuperConcrete
Abstract --> Concrete
SuperAbstract --> Abstract
Mixin1 --> Abstract
Mixin2B --> Concrete
Mixin2A --> Mixin2B

flowchart RL
SuperConcrete[SuperConcrete]
Concrete[Concrete]
Abstract[Abstract]
SuperAbstract[SuperAbstract]
Mixin1[Mixin1]
Mixin2B[Mixin2B]
Mixin2A[Mixin2A]

Concrete --> SuperConcrete
Abstract --> Concrete
SuperAbstract --> Abstract
Mixin1 --> Abstract
Mixin2B --> Concrete
Mixin2A --> Mixin2B

flowchart LR
SuperConcrete[SuperConcrete]
Concrete[Concrete]
Abstract[Abstract]
SuperAbstract[SuperAbstract]
Mixin1[Mixin1]
Mixin2B[Mixin2B]
Mixin2A[Mixin2A]

Concrete --> SuperConcrete
Abstract --> Concrete
SuperAbstract --> Abstract
Mixin1 --> Abstract
Mixin2B --> Concrete
Mixin2A --> Mixin2B

preload_modules¤

• Type list[str] | None 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 package from which the imported object originates must be accessible to the handler (see Finding modules).

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          preload_modules:
          - their_package

::: your_package.your_module
    options:
      preload_modules:
      - their_package

from their_package.their_module import their_object

__all__ = ["their_object"]

# rest of your code

show_bases¤

• Type bool True

Show the base classes of a class.

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

::: path.to.object
    options:
      show_bases: false

show_inheritance_diagram¤

Sponsors only — Insiders 1.7.0

• Type bool False

Show the inheritance diagram of a class using Mermaid.

With this option enabled, an inheritance diagram (as a flowchart) will be displayed after a class signature. Each node will act as a cross-reference and will bring you to the relevant class' documentation when clicking on it.

It should work out of the box with Material for MkDocs. For other themes, you must include Mermaid's Javascript code manually:

extra_javascript:
- https://unpkg.com/mermaid@10.9.0/dist/mermaid.min.js

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

::: path.to.object
    options:
      show_inheritance_diagram: false

class SuperAbstract:
    """Super abstract class."""
class Mixin1:
    """Mixin 1."""
class Abstract(SuperAbstract, Mixin1):
    """Abstract class."""
class Mixin2A:
    """Mixin 2A."""
class Mixin2B(Mixin2A):
    """Mixin 2B."""
class Concrete(Abstract, Mixin2B):
    """Concrete class."""
class SuperConcrete(Concrete):
    """Super concrete class."""

flowchart TD
SuperConcrete[SuperConcrete]
Concrete[Concrete]
Abstract[Abstract]
SuperAbstract[SuperAbstract]
Mixin1[Mixin1]
Mixin2B[Mixin2B]
Mixin2A[Mixin2A]

Concrete --> SuperConcrete
Abstract --> Concrete
SuperAbstract --> Abstract
Mixin1 --> Abstract
Mixin2B --> Concrete
Mixin2A --> Mixin2B

show_source¤

• Type bool True

Show the source code of this object.

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

::: path.to.object
    options:
      show_source: false

1
2

def some_function():
    ...

skip_local_inventory¤

• Type bool False

Whether to skip registering symbols in the objects inventory.

With this option enabled, re-rendering docstrings for objects from external inventories is possible with their cross-references pointing to the original external inventory, not local. Similarly, it becomes possible to render the same symbol several times in the same documentation, with only one canonical location being used for cross-references (preventing confusion in mkdocs-autorefs).

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          skip_local_inventory: false

::: path.to.module
    options:
      skip_local_inventory: true

bisect_left(a, x, lo=0, hi=None, *, key=None)

bisect_right(a, x, lo=0, hi=None, *, key=None)