Skip to content

plugin ¤

This module contains the "mkdocstrings" plugin for MkDocs.

The plugin instantiates a Markdown extension (MkdocstringsExtension), and adds it to the list of Markdown extensions used by mkdocs during the on_config event hook.

Once the documentation is built, the on_post_build event hook is triggered and calls the handlers.teardown() method. This method is used to teardown the handlers that were instantiated during documentation buildup.

Finally, when serving the documentation, it can add directories to watch during the on_serve event hook.

Classes:

Functions:

  • list_to_tuple –

    Decorater to convert lists to tuples in the arguments.

MkdocstringsPlugin ¤

MkdocstringsPlugin()

Bases: BasePlugin[PluginConfig]

An mkdocs plugin.

This plugin defines the following event hooks:

  • on_config
  • on_env
  • on_post_build

Check the Developing Plugins page of mkdocs for more information about its plugin system.

Methods:

Attributes:

handlers property ¤

handlers: Handlers

Get the instance of mkdocstrings.handlers.base.Handlers for this plugin/build.

Raises:

  • RuntimeError –

    If the plugin hasn't been initialized with a config.

Returns:

inventory_enabled property ¤

inventory_enabled: bool

Tell if the inventory is enabled or not.

Returns:

  • bool –

    Whether the inventory is enabled.

plugin_enabled property ¤

plugin_enabled: bool

Tell if the plugin is enabled or not.

Returns:

  • bool –

    Whether the plugin is enabled.

get_handler ¤

get_handler(handler_name: str) -> BaseHandler

Get a handler by its name. See mkdocstrings.handlers.base.Handlers.get_handler.

Parameters:

  • handler_name ¤

    (str) –

    The name of the handler.

Returns:

on_config ¤

on_config(config: MkDocsConfig) -> MkDocsConfig | None

Instantiate our Markdown extension.

Hook for the on_config event. In this hook, we instantiate our MkdocstringsExtension and add it to the list of Markdown extensions used by mkdocs.

We pass this plugin's configuration dictionary to the extension when instantiating it (it will need it later when processing markdown to get handlers and their global configurations).

Parameters:

  • config ¤

    (MkDocsConfig) –

    The MkDocs config object.

Returns:

  • MkDocsConfig | None –

    The modified config.

on_env ¤

on_env(
    env: Environment,
    config: MkDocsConfig,
    *args: Any,
    **kwargs: Any,
) -> None

Extra actions that need to happen after all Markdown rendering and before HTML rendering.

Hook for the on_env event.

  • Write mkdocstrings' extra files into the site dir.
  • Gather results from background inventory download tasks.

on_post_build ¤

on_post_build(config: MkDocsConfig, **kwargs: Any) -> None

Teardown the handlers.

Hook for the on_post_build event. This hook is used to teardown all the handlers that were instantiated and cached during documentation buildup.

For example, a handler could open a subprocess in the background and keep it open to feed it "autodoc" instructions and get back JSON data. If so, it should then close the subprocess at some point: the proper place to do this is in the handler's teardown method, which is indirectly called by this hook.

Parameters:

  • config ¤

    (MkDocsConfig) –

    The MkDocs config object.

  • **kwargs ¤

    (Any, default: {} ) –

    Additional arguments passed by MkDocs.

PluginConfig ¤

Bases: Config

The configuration options of mkdocstrings, written in mkdocs.yml.

Attributes:

  • custom_templates –

    Location of custom templates to use when rendering API objects.

  • default_handler –

    The default handler to use. The value is the name of the handler module. Default is "python".

  • enable_inventory –

    Whether to enable object inventory creation.

  • enabled –

    Whether to enable the plugin. Default is true. If false, mkdocstrings will not collect or render anything.

  • handlers –

    Global configuration of handlers.

custom_templates class-attribute instance-attribute ¤

custom_templates = Optional(Dir(exists=True))

Location of custom templates to use when rendering API objects.

Value should be the path of a directory relative to the MkDocs configuration file.

default_handler class-attribute instance-attribute ¤

default_handler = Type(str, default='python')

The default handler to use. The value is the name of the handler module. Default is "python".

enable_inventory class-attribute instance-attribute ¤

enable_inventory = Optional(Type(bool))

Whether to enable object inventory creation.

enabled class-attribute instance-attribute ¤

enabled = Type(bool, default=True)

Whether to enable the plugin. Default is true. If false, mkdocstrings will not collect or render anything.

handlers class-attribute instance-attribute ¤

handlers = Type(dict, default={})

Global configuration of handlers.

You can set global configuration per handler, applied everywhere, but overridable in each "autodoc" instruction. Example:

plugins:
  - mkdocstrings:
      handlers:
        python:
          options:
            option1: true
            option2: "value"
        rust:
          options:
            option9: 2

list_to_tuple ¤

list_to_tuple(
    function: Callable[P, R]
) -> Callable[P, R]

Decorater to convert lists to tuples in the arguments.