Signatures options¤

annotations_path¤

• Type str "brief"

The verbosity for annotations path.

Possible values:

• brief (recommended): render only the last component of each type path, not their full paths. For example, it will render Sequence[Path] and not typing.Sequence[pathlib.Path]. Brief annotations will cross-reference the right object anyway, and show the full path in a tooltip when hovering them.
• source: render annotations as written in the source. For example if you imported typing as t, it will render typing.Sequence as t.Sequence. Each part will cross-reference the relevant object: t will link to the typing module and Sequence will link to the Sequence type.
• full: render annotations with their full path (the opposite of brief). For example if you import Sequence and Pattern from typing and annoate something using Sequence[Pattern], it will render as typing.Sequence[typing.Pattern], with each part cross-referencing the corresponding object.

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          annotations_path: brief

::: path.to.module
    options:
      annotations_path: source

import markdown
import markupsafe


def convert(text: str, md: markdown.Markdown) -> markupsafe.Markup:
    """Convert text to Markdown.

    Parameters:
        text: The text to convert.
        md: A Markdown instance.

    Returns:
        Converted markup.
    """
    return markupsafe.Markup(md.convert(text))

import markdown
from markupsafe import Markup


def convert(text: str, md: markdown.Markdown) -> Markup:
    """Convert text to Markdown.

    Parameters:
        text: The text to convert.
        md: A Markdown instance.

    Returns:
        Converted markup.
    """
    return Markup(md.convert(text))

from markdown import Markdown
from markupsafe import Markup


def convert(text: str, md: Markdown) -> Markup:
    """Convert text to Markdown.

    Parameters:
        text: The text to convert.
        md: A Markdown instance.

    Returns:
        Converted markup.
    """
    return Markup(md.convert(text))

line_length¤

• Type int 60

Maximum line length when formatting code/signatures.

When separating signatures from headings with the separate_signature option, the Python handler will try to format the signatures using Black and the specified line length.

If Black is not installed, the handler issues an INFO log once.

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          separate_signature: true
          line_length: 60

::: path.to.module
    options:
      separate_signature: true
      line_length: 80

long_function_name(
    long_parameter_1="hello",
    long_parameter_2="world",
)

long_function_name(long_parameter_1="hello", long_parameter_2="world")

modernize_annotations¤

Sponsors only — Insiders 1.8.0 — This feature also requires Griffe Insiders to be installed.

• Type bool False

Modernize annotations with latest features and PEPs of the Python language.

The Python language keeps evolving, and often library developers must continue to support a few minor versions of Python. Therefore they cannot use some features that were introduced in the latest versions.

Yet this doesn't mean they can't enjoy latest features in their docs: Griffe allows to "modernize" expressions, for example by replacing typing.Union with PEP 604 type unions |. Thanks to this, mkdocstrings' Python handler can automatically transform type annotations into their modern equivalent. This improves consistency in your docs, and shows users how to use your code with the latest features of the language.

Modernizations applied:

• typing.Dict[A, B] becomes dict[A, B]
• typing.List[A] becomes list[A]
• typing.Set[A] becomes set[A]
• typing.Tuple[A] becomes tuple[A]
• typing.Union[A, B] becomes A | B
• typing.Optional[A] becomes A | None

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          modernize_annotations: true

::: path.to.object
    options:
      modernize_annotations: false

from typing import Optional, Union, List

example: Optional[Union[int, List[int]]] = None

example: Optional[Union[int, List[int]]] = None

example: int | list[int] | None = None

show_signature¤

• Type bool True

Show methods and functions signatures.

Without it, just the function/method name is rendered.

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          show_signature: true

::: path.to.module
    options:
      show_signature: false

show_signature_annotations¤

• Type bool False

Show the type annotations in methods and functions signatures.

Since the heading can become quite long when annotations are rendered, it is usually best to separate the signature from the heading.

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          separate_signature: true
          show_signature_annotations: true

::: path.to.module
    options:
      separate_signature: true
      show_signature_annotations: false

function(
    param1: list[int | float],
    param2: bool | None = None,
) -> float

function(param1, param2=None)

separate_signature¤

• Type bool False

Whether to put the whole signature in a code block below the heading.

When separating signatures from headings, the Python handler will try to format the signatures using Black and the specified line length.

If Black is not installed, the handler issues an INFO log once.

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          separate_signature: false

::: path.to.module
    options:
      separate_signature: true

function(param1, param2=None)

signature_crossrefs¤

Insiders 1.0.0

Whether to render cross-references for type annotations in signatures.

When signatures are separated from headings with the separate_signature option and type annotations are shown with the show_signature_annotations option, this option will render a cross-reference (link) for each type annotation in the signature.

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          separate_signature: true
          show_signature_annotations: true
          signature_crossrefs: false

::: path.to.module
    options:
      separate_signature: true
      show_signature_annotations: true
      signature_crossrefs: true

do_format_code(code: str, line_length: int) -> str

do_format_code(code: str, line_length: int) -> str

unwrap_annotated¤

• Type bool False

Whether to unwrap Annotated types to show only the type without the annotations.

For example, unwrapping Annotated[int, Gt(10)] will render int.

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          unwrap_annotated: false

::: path.to.module
    options:
      unwrap_annotated: true