Skip to content

handler ¤

This module implements a handler for the Shell language.

Classes:

Functions:

  • get_handler –

    Simply return an instance of ShellHandler.

ShellHandler ¤

ShellHandler(
    handler: str,
    theme: str,
    custom_templates: str | None = None,
    config_file_path: str | None = None,
)

Bases: BaseHandler

The Shell handler class.

Methods:

  • collect –

    Collect data given an identifier and selection configuration.

  • render –

    Render a template using provided data and configuration options.

  • update_env –

    Update the Jinja environment with any custom settings/filters/options for this handler.

Attributes:

  • default_config (dict) –

    The default configuration options.

  • domain (str) –

    The cross-documentation domain/language for this handler.

  • enable_inventory (bool) –

    Whether this handler is interested in enabling the creation of the objects.inv Sphinx inventory file.

  • fallback_config (dict) –

    The configuration used to collect item during autorefs fallback.

  • fallback_theme –

    The theme to fallback to.

default_config class-attribute ¤

default_config: dict = {
    "show_root_heading": False,
    "show_root_toc_entry": True,
    "heading_level": 2,
}

The default configuration options.

Option Type Description Default
show_root_heading bool Show the heading of the object at the root of the documentation tree. False
show_root_toc_entry bool If the root heading is not shown, at least add a ToC entry for it. True
heading_level int The initial heading level to use. 2

domain class-attribute instance-attribute ¤

domain: str = 'shell'

The cross-documentation domain/language for this handler.

enable_inventory class-attribute instance-attribute ¤

enable_inventory: bool = False

Whether this handler is interested in enabling the creation of the objects.inv Sphinx inventory file.

fallback_config class-attribute ¤

fallback_config: dict = {'fallback': True}

The configuration used to collect item during autorefs fallback.

fallback_theme class-attribute instance-attribute ¤

fallback_theme = 'material'

The theme to fallback to.

collect ¤

collect(
    identifier: str, config: MutableMapping[str, Any]
) -> CollectorItem

Collect data given an identifier and selection configuration.

In the implementation, you typically call a subprocess that returns JSON, and load that JSON again into a Python dictionary for example, though the implementation is completely free.

Parameters:

  • identifier (str) –

    An identifier that was found in a markdown document for which to collect data. For example, in Python, it would be 'mkdocstrings.handlers' to collect documentation about the handlers module. It can be anything that you can feed to the tool of your choice.

  • config (MutableMapping[str, Any]) –

    All configuration options for this handler either defined globally in mkdocs.yml or locally overridden in an identifier block by the user.

Returns:

  • CollectorItem –

    Anything you want, as long as you can feed it to the render method.

render ¤

render(
    data: CollectorItem, config: Mapping[str, Any]
) -> str

Render a template using provided data and configuration options.

Parameters:

  • data (CollectorItem) –

    The data to render that was collected above in collect().

  • config (Mapping[str, Any]) –

    All configuration options for this handler either defined globally in mkdocs.yml or locally overridden in an identifier block by the user.

Returns:

  • str –

    The rendered template as HTML.

update_env ¤

update_env(md: Markdown, config: dict) -> None

Update the Jinja environment with any custom settings/filters/options for this handler.

Parameters:

  • md (Markdown) –

    The Markdown instance. Useful to add functions able to convert Markdown into the environment filters.

  • config (dict) –

    Configuration options for mkdocs and mkdocstrings, read from mkdocs.yml. See the source code of mkdocstrings.plugin.MkdocstringsPlugin.on_config to see what's in this dictionary.

get_handler ¤

get_handler(
    theme: str,
    custom_templates: str | None = None,
    config_file_path: str | None = None,
    **config: Any,
) -> ShellHandler

Simply return an instance of ShellHandler.

Parameters:

  • theme (str) –

    The theme to use when rendering contents.

  • custom_templates (str | None, default: None ) –

    Directory containing custom templates.

  • config_file_path (str | None, default: None ) –

    The MkDocs configuration file path.

  • **config (Any, default: {} ) –

    Configuration passed to the handler.

Returns: