mkdocstrings ¤

Bases: BlockProcessor

Our "autodoc" Markdown block processor.

It has a test method that tells if a block matches a criterion, and a run method that processes it.

It also has utility methods allowing to get handlers and their configuration easily, useful when processing a matched block.

Parameters:

• md ¤

  (Markdown) –

  A markdown.Markdown instance.

• handlers ¤

  (Handlers) –

  The handlers container.

• autorefs ¤

  (AutorefsPlugin) –

  The autorefs plugin instance.

Methods:

• run –

  Run code on the matched blocks.

• test –

  Match our autodoc instructions.

Attributes:

• md –

  The Markdown instance.

• regex –

  The regular expression to match our autodoc instructions.

md = md

regex = compile(
    "^(?P<heading>#{1,6} *|)::: ?(?P<name>.+?) *$",
    flags=MULTILINE,
)

run(parent: Element, blocks: MutableSequence[str]) -> None

test(parent: Element, block: str) -> bool

The base handler class.

Inherit from this class to implement a handler.

You will have to implement the collect and render methods. You can also implement the teardown method, and override the update_env method, to add more filters to the Jinja environment, making them available in your Jinja templates.

To define a fallback theme, add a fallback_theme class-variable. To add custom CSS, add an extra_css variable or create an 'style.css' file beside the templates.

If the given theme is not supported (it does not exist), it will look for a fallback_theme attribute in self to use as a fallback theme.

Other Parameters:

• theme (str) –

  The theme to use.

• custom_templates (str | None) –

  The path to custom templates.

• mdx (list[str | Extension]) –

  A list of Markdown extensions to use.

• mdx_config (Mapping[str, Mapping[str, Any]]) –

  Configuration for the Markdown extensions.

Methods:

• collect –

  Collect data given an identifier and user configuration.

• do_convert_markdown –

  Render Markdown text; for use inside templates.

• do_heading –

  Render an HTML heading and register it for the table of contents. For use inside templates.

• get_aliases –

  Return the possible aliases for a given identifier.

• get_extended_templates_dirs –

  Load template extensions for the given handler, return their templates directories.

• get_headings –

  Return and clear the headings gathered so far.

• get_inventory_urls –

  Return the URLs (and configuration options) of the inventory files to download.

• get_options –

  Get combined options.

• get_templates_dir –

  Return the path to the handler's templates directory.

• load_inventory –

  Yield items and their URLs from an inventory file streamed from in_file.

• render –

  Render a template using provided data and configuration options.

• teardown –

  Teardown the handler.

• update_env –

  Update the Jinja environment.

Attributes:

• custom_templates –

  The path to custom templates.

• domain (str) –

  The handler's domain, used to register objects in the inventory, for example "py".

• enable_inventory (bool) –

  Whether the inventory creation is enabled.

• env –

  The Jinja environment.

• extra_css (str) –

  Extra CSS.

• fallback_config (dict) –

  Fallback configuration when searching anchors for identifiers.

• fallback_theme (str) –

  Fallback theme to use when a template isn't found in the configured theme.

• md (Markdown) –

  The Markdown instance.

• mdx –

  The Markdown extensions to use.

• mdx_config –

  The configuration for the Markdown extensions.

• name (str) –

  The handler's name, for example "python".

• outer_layer (bool) –

  Whether we're in the outer Markdown conversion layer.

• theme –

  The selected theme.

custom_templates = custom_templates

domain: str = ''

enable_inventory: bool = False

env = Environment(
    autoescape=True,
    loader=FileSystemLoader(paths),
    auto_reload=False,
)

extra_css: str = ''

fallback_config: dict = {}

fallback_theme: str = ''

md: Markdown

mdx = mdx

mdx_config = mdx_config

name: str = ''

outer_layer: bool

theme = theme

collect(
    identifier: str, options: HandlerOptions
) -> CollectorItem

do_convert_markdown(
    text: str,
    heading_level: int,
    html_id: str = "",
    *,
    strip_paragraph: bool = False,
    autoref_hook: AutorefsHookInterface | None = None,
) -> Markup

do_heading(
    content: Markup,
    heading_level: int,
    *,
    role: str | None = None,
    hidden: bool = False,
    toc_label: str | None = None,
    **attributes: str,
) -> Markup

get_aliases(identifier: str) -> tuple[str, ...]

get_extended_templates_dirs(handler: str) -> list[Path]

get_headings() -> Sequence[Element]

get_inventory_urls() -> list[tuple[str, dict[str, Any]]]

get_options(
    local_options: Mapping[str, Any],
) -> HandlerOptions

get_templates_dir(handler: str | None = None) -> Path

load_inventory(
    in_file: BinaryIO,
    url: str,
    base_url: str | None = None,
    **kwargs: Any,
) -> Iterator[tuple[str, str]]

render(data: CollectorItem, options: HandlerOptions) -> str

teardown() -> None

update_env(*args: Any, **kwargs: Any) -> None

Bases: Exception

An exception raised when some collection of data failed.

A collection of handlers.

Do not instantiate this directly. The plugin will keep one instance of this for the purpose of caching. Use mkdocstrings.MkdocstringsPlugin.get_handler for convenient access.

Parameters:

• theme ¤

  (str) –

  The theme to use.

• default ¤

  (str) –

  The default handler to use.

• inventory_project ¤

  (str) –

  The project name to use in the inventory.

• inventory_version ¤

  (str, default: '0.0.0' ) –

  The project version to use in the inventory.

• handlers_config ¤

  (dict[str, HandlerConfig] | None, default: None ) –

  The handlers configuration.

• custom_templates ¤

  (str | None, default: None ) –

  The path to custom templates.

• mdx ¤

  (Sequence[str | Extension] | None, default: None ) –

  A list of Markdown extensions to use.

• mdx_config ¤

  (Mapping[str, Any] | None, default: None ) –

  Configuration for the Markdown extensions.

• tool_config ¤

  (Any) –

  Tool configuration to pass down to handlers.

Methods:

• get_anchors –

  Return the canonical HTML anchor for the identifier, if any of the seen handlers can collect it.

• get_handler –

  Get a handler thanks to its name.

• get_handler_config –

  Return the global configuration of the given handler.

• get_handler_name –

  Return the handler name defined in an "autodoc" instruction YAML configuration, or the global default handler.

• teardown –

  Teardown all cached handlers and clear the cache.

Attributes:

• inventory (Inventory) –

  The objects inventory.

• seen_handlers (Iterable[BaseHandler]) –

  Get the handlers that were encountered so far throughout the build.

inventory: Inventory = Inventory(
    project=inventory_project, version=inventory_version
)

seen_handlers: Iterable[BaseHandler]

get_anchors(identifier: str) -> tuple[str, ...]

get_handler(
    name: str, handler_config: dict | None = None
) -> BaseHandler

get_handler_config(name: str) -> dict

get_handler_name(config: dict) -> str

teardown() -> None

Bases: Treeprocessor

Shift levels of all Markdown headings according to the configured base level.

Parameters:

• md ¤

  (Markdown) –

  A markdown.Markdown instance.

• shift_by ¤

  (int) –

  The number of heading "levels" to add to every heading.

Methods:

• run –

  Shift the levels of all headings in the document.

Attributes:

• name (str) –

  The name of the treeprocessor.

• regex (Pattern) –

  The regex to match heading tags.

• shift_by (int) –

  The number of heading "levels" to add to every heading. <h2> with shift_by = 3 becomes <h5>.

name: str = 'mkdocstrings_headings'

regex: Pattern = compile('([Hh])([1-6])')

shift_by: int = shift_by

run(root: Element) -> None

Bases: Highlight

Code highlighter that tries to match the Markdown configuration.

Picking up the global config and defaults works only if you use the codehilite or pymdownx.highlight (recommended) Markdown extension.

• If you use pymdownx.highlight, highlighting settings are picked up from it, and the default CSS class is .highlight. This also means the default of guess_lang: false.

• Otherwise, if you use the codehilite extension, settings are picked up from it, and the default CSS class is .codehilite. Also consider setting guess_lang: false.

• If neither are added to markdown_extensions, highlighting is enabled anyway. This is for backwards compatibility. If you really want to disable highlighting even in mkdocstrings, add one of these extensions anyway and set use_pygments: false.

The underlying implementation is pymdownx.highlight regardless.

Parameters:

• md ¤

  (Markdown) –

  The Markdown instance to read configs from.

Methods:

• highlight –

  Highlight a code-snippet.

highlight(
    src: str,
    language: str | None = None,
    *,
    inline: bool = False,
    dedent: bool = True,
    linenums: bool | None = None,
    **kwargs: Any,
) -> str

Bases: Treeprocessor

Prepend the configured prefix to IDs of all HTML elements.

Parameters:

• md ¤

  (Markdown) –

  A markdown.Markdown instance.

• id_prefix ¤

  (str) –

  The prefix to add to every ID. It is prepended without any separator.

Methods:

• run –

  Prepend the configured prefix to all IDs in the document.

Attributes:

• id_prefix (str) –

  The prefix to add to every ID. It is prepended without any separator; specify your own separator if needed.

• name (str) –

  The name of the treeprocessor.

id_prefix: str = id_prefix

name: str = 'mkdocstrings_ids'

run(root: Element) -> None

Bases: dict

Inventory of collected and rendered objects.

Parameters:

• items ¤

  (list[InventoryItem] | None, default: None ) –

  A list of items.

• project ¤

  (str, default: 'project' ) –

  The project name.

• version ¤

  (str, default: '0.0.0' ) –

  The project version.

Methods:

• format_sphinx –

  Format this inventory as a Sphinx objects.inv file.

• parse_sphinx –

  Parse a Sphinx v2 inventory file and return an Inventory from it.

• register –

  Create and register an item.

Attributes:

• project –

  The project name.

• version –

  The project version.

project = project

version = version

format_sphinx() -> bytes

parse_sphinx(
    in_file: BinaryIO,
    *,
    domain_filter: Collection[str] = (),
) -> Inventory

register(
    name: str,
    domain: str,
    role: str,
    uri: str,
    priority: int = 1,
    dispname: str | None = None,
) -> None

Inventory item.

Parameters:

• name ¤

  (str) –

  The item name.

• domain ¤

  (str) –

  The item domain, like 'python' or 'crystal'.

• role ¤

  (str) –

  The item role, like 'class' or 'method'.

• uri ¤

  (str) –

  The item URI.

• priority ¤

  (int, default: 1 ) –

  The item priority. Only used internally by mkdocstrings and Sphinx.

• dispname ¤

  (str | None, default: None ) –

  The item display name.

Methods:

• format_sphinx –

  Format this item as a Sphinx inventory line.

• parse_sphinx –

  Parse a line from a Sphinx v2 inventory file and return an InventoryItem from it.

Attributes:

• dispname (str) –

  The item display name.

• domain (str) –

  The item domain.

• name (str) –

  The item name.

• priority (int) –

  The item priority.

• role (str) –

  The item role.

• sphinx_item_regex –

  Regex to parse a Sphinx v2 inventory line.

• uri (str) –

  The item URI.

dispname: str = dispname or name

domain: str = domain

name: str = name

priority: int = priority

role: str = role

sphinx_item_regex = compile(
    "^(.+?)\\s+(\\S+):(\\S+)\\s+(-?\\d+)\\s+(\\S+)\\s*(.*)$"
)

uri: str = uri

format_sphinx() -> str

parse_sphinx(line: str) -> InventoryItem

Bases: LoggerAdapter

A logger adapter to prefix messages.

This adapter also adds an additional parameter to logging methods called once: if True, the message will only be logged once.

Examples:

In Python code:

>>> logger = get_logger("myplugin")
>>> logger.debug("This is a debug message.")
>>> logger.info("This is an info message.", once=True)

In Jinja templates (logger available in context as log):

{{ log.debug("This is a debug message.") }}
{{ log.info("This is an info message.", once=True) }}

Parameters:

• prefix ¤

  (str) –

  The string to insert in front of every message.

• logger ¤

  (Logger) –

  The logger instance.

Methods:

• log –

  Log a message.

• process –

  Process the message.

Attributes:

• prefix –

  The prefix to insert in front of every message.

prefix = prefix

log(
    level: int, msg: object, *args: object, **kwargs: object
) -> None

process(
    msg: str, kwargs: MutableMapping[str, Any]
) -> tuple[str, Any]

Bases: Extension

Our Markdown extension.

It cannot work outside of mkdocstrings.

Parameters:

• handlers ¤

  (Handlers) –

  The handlers container.

• autorefs ¤

  (AutorefsPlugin) –

  The autorefs plugin instance.

• **kwargs ¤

  (Any, default: {} ) –

  Keyword arguments used by markdown.extensions.Extension.

Methods:

• extendMarkdown –

  Register the extension.

extendMarkdown(md: Markdown) -> None

Bases: Extension

Extension that should always be added to Markdown sub-documents that handlers request (and only them).

Parameters:

• headings ¤

  (list[Element]) –

  A list that will be populated with all HTML heading elements encountered in the document.

Methods:

• extendMarkdown –

  Register the extension.

Attributes:

• headings –

  The list that will be populated with all HTML heading elements encountered in the document.

headings = headings

extendMarkdown(md: Markdown) -> None

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:

• get_handler –

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

• on_config –

  Instantiate our Markdown extension.

• on_env –

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

• on_post_build –

  Teardown the handlers.

Attributes:

• css_filename (str) –

  The path of the CSS file to write in the site directory.

• handlers (Handlers) –

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

• inventory_enabled (bool) –

  Tell if the inventory is enabled or not.

• plugin_enabled (bool) –

  Tell if the plugin is enabled or not.

css_filename: str = 'assets/_mkdocstrings.css'

handlers: Handlers

inventory_enabled: bool

plugin_enabled: bool

get_handler(handler_name: str) -> BaseHandler

on_config(config: MkDocsConfig) -> MkDocsConfig | None

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

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

Bases: Treeprocessor

Unwraps the

element around the whole output.

Methods:

• run –

  Unwrap the root element if it's a single <p> element.

Attributes:

• name (str) –

  The name of the treeprocessor.

• strip (bool) –

  Whether to strip <p> elements or not.

name: str = 'mkdocstrings_strip_paragraph'

strip: bool = False

run(root: Element) -> Element | None

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 = Optional(Dir(exists=True))

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

enable_inventory = Optional(Type(bool))

enabled = Type(bool, default=True)

handlers = Type(dict, default={})

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

A wrapper class to allow logging in templates.

The logging methods provided by this class all accept two parameters:

• msg: The message to log.
• once: If True, the message will only be logged once.

Methods:

• debug –

  Function to log a DEBUG message.

• info –

  Function to log an INFO message.

• warning –

  Function to log a WARNING message.

• error –

  Function to log an ERROR message.

• critical –

  Function to log a CRITICAL message.

Parameters:

• logger ¤

  (LoggerAdapter) –

  A logger adapter.

Attributes:

• critical –

  Log a CRITICAL message.

• debug –

  Log a DEBUG message.

• error –

  Log an ERROR message.

• info –

  Log an INFO message.

• warning –

  Log a WARNING message.

critical = get_template_logger_function(critical)

debug = get_template_logger_function(debug)

error = get_template_logger_function(error)

info = get_template_logger_function(info)

warning = get_template_logger_function(warning)

Bases: Exception

An exception raised to tell a theme is not supported.