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.

RENDERING_OPTS_KEY: str = 'rendering' module-attribute ¤

The name of the rendering parameter in YAML configuration blocks.

SELECTION_OPTS_KEY: str = 'selection' module-attribute ¤

The name of the selection parameter in YAML configuration blocks.

MkdocstringsPlugin() ¤

Bases: BasePlugin

An mkdocs plugin.

This plugin defines the following event hooks:

  • on_config
  • on_env
  • on_post_build
  • on_serve

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

Source code in mkdocstrings/plugin.py
108
109
110
111
def __init__(self) -> None:
    """Initialize the object."""
    super().__init__()
    self._handlers: Optional[Handlers] = None

config_scheme: Tuple[Tuple[str, MkType]] = (('watch', MkType(list, default=[])), ('handlers', MkType(dict, default={})), ('default_handler', MkType(str, default='python')), ('custom_templates', MkType(str, default=None)), ('enable_inventory', MkType(bool, default=None)), ('enabled', MkType(bool, default=True))) class-attribute ¤

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

Available options are:

  • watch (deprecated): A list of directories to watch. Only used when serving the documentation with mkdocs. Whenever a file changes in one of directories, the whole documentation is built again, and the browser refreshed. Deprecated in favor of the now built-in watch feature of MkDocs.
  • default_handler: The default handler to use. The value is the name of the handler module. Default is "python".
  • enabled: Whether to enable the plugin. Default is true. If false, mkdocstrings will not collect or render anything.
  • handlers: 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:
            selection_opt: true
            rendering_opt: "value"
        rust:
          options:
            selection_opt: 2

handlers: Handlers property ¤

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

Raises:

Type Description
RuntimeError

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

Returns:

Type Description
Handlers

An instance of mkdocstrings.handlers.base.Handlers (the same throughout the build).

inventory_enabled: bool property ¤

Tell if the inventory is enabled or not.

Returns:

Type Description
bool

Whether the inventory is enabled.

plugin_enabled: bool property ¤

Tell if the plugin is enabled or not.

Returns:

Type Description
bool

Whether the plugin is enabled.

get_handler(handler_name) ¤

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

Parameters:

Name Type Description Default
handler_name str

The name of the handler.

required

Returns:

Type Description
BaseHandler

An instance of a subclass of BaseHandler.

Source code in mkdocstrings/plugin.py
303
304
305
306
307
308
309
310
311
312
def get_handler(self, handler_name: str) -> BaseHandler:
    """Get a handler by its name. See [mkdocstrings.handlers.base.Handlers.get_handler][].

    Arguments:
        handler_name: The name of the handler.

    Returns:
        An instance of a subclass of [`BaseHandler`][mkdocstrings.handlers.base.BaseHandler].
    """
    return self.handlers.get_handler(handler_name)

on_config(config, **kwargs) ¤

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:

Name Type Description Default
config Config

The MkDocs config object.

required
**kwargs Any

Additional arguments passed by MkDocs.

{}

Returns:

Type Description
Config

The modified config.

Source code in mkdocstrings/plugin.py
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
def on_config(self, config: Config, **kwargs: Any) -> Config:  # noqa: W0613 (unused arguments)
    """Instantiate our Markdown extension.

    Hook for the [`on_config` event](https://www.mkdocs.org/user-guide/plugins/#on_config).
    In this hook, we instantiate our [`MkdocstringsExtension`][mkdocstrings.extension.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).

    Arguments:
        config: The MkDocs config object.
        **kwargs: Additional arguments passed by MkDocs.

    Returns:
        The modified config.
    """
    if not self.plugin_enabled:
        log.debug("Plugin is not enabled. Skipping.")
        return config
    log.debug("Adding extension to the list")

    theme_name = None
    if config["theme"].name is None:
        theme_name = os.path.dirname(config["theme"].dirs[0])
    else:
        theme_name = config["theme"].name

    to_import: InventoryImportType = []
    for handler_name, conf in self.config["handlers"].items():
        for import_item in conf.pop("import", ()):
            if isinstance(import_item, str):
                import_item = {"url": import_item}
            to_import.append((handler_name, import_item))

    extension_config = {
        "site_name": config["site_name"],
        "config_file_path": config["config_file_path"],
        "theme_name": theme_name,
        "mdx": config["markdown_extensions"],
        "mdx_configs": config["mdx_configs"],
        "mkdocstrings": self.config,
    }
    self._handlers = Handlers(extension_config)

    try:  # noqa: WPS229
        # If autorefs plugin is explicitly enabled, just use it.
        autorefs = config["plugins"]["autorefs"]
        log.debug(f"Picked up existing autorefs instance {autorefs!r}")
    except KeyError:
        # Otherwise, add a limited instance of it that acts only on what's added through `register_anchor`.
        autorefs = AutorefsPlugin()
        autorefs.scan_toc = False
        config["plugins"]["autorefs"] = autorefs
        log.debug(f"Added a subdued autorefs instance {autorefs!r}")
    # Add collector-based fallback in either case.
    autorefs.get_fallback_anchor = self.handlers.get_anchors

    mkdocstrings_extension = MkdocstringsExtension(extension_config, self.handlers, autorefs)
    config["markdown_extensions"].append(mkdocstrings_extension)

    config["extra_css"].insert(0, self.css_filename)  # So that it has lower priority than user files.

    self._inv_futures = []
    if to_import:
        inv_loader = futures.ThreadPoolExecutor(4)
        for handler_name, import_item in to_import:  # noqa: WPS440
            future = inv_loader.submit(
                self._load_inventory, self.get_handler(handler_name).load_inventory, **import_item
            )
            self._inv_futures.append(future)
        inv_loader.shutdown(wait=False)

    if self.config["watch"]:
        self._warn_about_watch_option()

    return config

on_env(env, config, *args, **kwargs) ¤

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.
Source code in mkdocstrings/plugin.py
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
def on_env(self, env, config: Config, *args, **kwargs) -> None:
    """Extra actions that need to happen after all Markdown rendering and before HTML rendering.

    Hook for the [`on_env` event](https://www.mkdocs.org/user-guide/plugins/#on_env).

    - Write mkdocstrings' extra files into the site dir.
    - Gather results from background inventory download tasks.
    """
    if not self.plugin_enabled:
        return
    if self._handlers:
        css_content = "\n".join(handler.extra_css for handler in self.handlers.seen_handlers)
        write_file(css_content.encode("utf-8"), os.path.join(config["site_dir"], self.css_filename))

        if self.inventory_enabled:
            log.debug("Creating inventory file objects.inv")
            inv_contents = self.handlers.inventory.format_sphinx()
            write_file(inv_contents, os.path.join(config["site_dir"], "objects.inv"))

    if self._inv_futures:
        log.debug(f"Waiting for {len(self._inv_futures)} inventory download(s)")
        futures.wait(self._inv_futures, timeout=30)
        for page, identifier in collections.ChainMap(*(fut.result() for fut in self._inv_futures)).items():
            config["plugins"]["autorefs"].register_url(page, identifier)
        self._inv_futures = []

on_post_build(config, **kwargs) ¤

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 collector's teardown method, which is indirectly called by this hook.

Parameters:

Name Type Description Default
config Config

The MkDocs config object.

required
**kwargs Any

Additional arguments passed by MkDocs.

{}
Source code in mkdocstrings/plugin.py
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
def on_post_build(
    self, config: Config, **kwargs: Any
) -> None:  # noqa: W0613,R0201 (unused arguments, cannot be static)
    """Teardown the handlers.

    Hook for the [`on_post_build` event](https://www.mkdocs.org/user-guide/plugins/#on_post_build).
    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 collector's `teardown` method, which is indirectly called by this hook.

    Arguments:
        config: The MkDocs config object.
        **kwargs: Additional arguments passed by MkDocs.
    """
    if not self.plugin_enabled:
        return

    for future in self._inv_futures:
        future.cancel()

    if self._handlers:
        log.debug("Tearing handlers down")
        self.handlers.teardown()

on_serve(server, config, builder, *args, **kwargs) ¤

Watch directories.

Hook for the on_serve event. In this hook, we add the directories specified in the plugin's configuration to the list of directories watched by mkdocs. Whenever a change occurs in one of these directories, the documentation is built again and the site reloaded.

Parameters:

Name Type Description Default
server LiveReloadServer

The livereload server instance.

required
config Config

The MkDocs config object (unused).

required
builder Callable

The function to build the site.

required
*args Any

Additional arguments passed by MkDocs.

()
**kwargs Any

Additional arguments passed by MkDocs.

{}
Source code in mkdocstrings/plugin.py
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
def on_serve(
    self, server: LiveReloadServer, config: Config, builder: Callable, *args: Any, **kwargs: Any
) -> None:  # noqa: W0613 (unused arguments)
    """Watch directories.

    Hook for the [`on_serve` event](https://www.mkdocs.org/user-guide/plugins/#on_serve).
    In this hook, we add the directories specified in the plugin's configuration to the list of directories
    watched by `mkdocs`. Whenever a change occurs in one of these directories, the documentation is built again
    and the site reloaded.

    Arguments:
        server: The `livereload` server instance.
        config: The MkDocs config object (unused).
        builder: The function to build the site.
        *args: Additional arguments passed by MkDocs.
        **kwargs: Additional arguments passed by MkDocs.
    """
    if not self.plugin_enabled:
        return
    if self.config["watch"]:
        for element in self.config["watch"]:
            log.debug(f"Adding directory '{element}' to watcher")
            server.watch(element, builder)

list_to_tuple(function) ¤

Decorater to convert lists to tuples in the arguments.

Source code in mkdocstrings/plugin.py
45
46
47
48
49
50
51
52
53
54
def list_to_tuple(function: Callable[..., Any]) -> Callable[..., Any]:
    """Decorater to convert lists to tuples in the arguments."""

    def wrapper(*args: Any, **kwargs: Any):
        safe_args = [tuple(item) if isinstance(item, list) else item for item in args]
        if kwargs:
            kwargs = {key: tuple(value) if isinstance(value, list) else value for key, value in kwargs.items()}
        return function(*safe_args, **kwargs)

    return wrapper