Skip to content

extension ¤

This module holds the code of the Markdown extension responsible for matching "autodoc" instructions.

The extension is composed of a Markdown block processor that matches indented blocks starting with a line like ::: identifier.

For each of these blocks, it uses a handler to collect documentation about the given identifier and render it with Jinja templates.

Both the collection and rendering process can be configured by adding YAML configuration under the "autodoc" instruction:

::: some.identifier
    handler: python
    options:
      option1: value1
      option2:
      - value2a
      - value2b
      option_x: etc

Classes:

AutoDocProcessor ¤

AutoDocProcessor(
    parser: BlockParser,
    md: Markdown,
    config: dict,
    handlers: Handlers,
    autorefs: AutorefsPlugin,
)

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:

Methods:

  • run –

    Run code on the matched blocks.

  • test –

    Match our autodoc instructions.

run ¤

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

Run code on the matched blocks.

The identifier and configuration lines are retrieved from a matched block and used to collect and render an object.

Parameters:

test ¤

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

Match our autodoc instructions.

Parameters:

  • parent ¤

    (Element) –

    The parent element in the XML tree.

  • block ¤

    (str) –

    The block to be tested.

Returns:

  • bool –

    Whether this block should be processed or not.

MkdocstringsExtension ¤

MkdocstringsExtension(
    config: dict,
    handlers: Handlers,
    autorefs: AutorefsPlugin,
    **kwargs: Any,
)

Bases: Extension

Our Markdown extension.

It cannot work outside of mkdocstrings.

Parameters:

  • config ¤

    (dict) –

    The configuration items from mkdocs and mkdocstrings that must be passed to the block processor when instantiated in extendMarkdown.

  • handlers ¤

    (Handlers) –

    The handlers container.

  • autorefs ¤

    (AutorefsPlugin) –

    The autorefs plugin instance.

  • **kwargs ¤

    (Any, default: {} ) –

    Keyword arguments used by markdown.extensions.Extension.

Methods:

extendMarkdown ¤

extendMarkdown(md: Markdown) -> None

Register the extension.

Add an instance of our AutoDocProcessor to the Markdown parser.

Parameters:

  • md ¤

    (Markdown) –

    A markdown.Markdown instance.