Signatures options

{#option-annotations_path}

`annotations_path`

:octicons-package-24: Type [str][] :material-equal: "brief"{ title="default value" }

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

/// admonition | Preview type: preview

//// tab | Brief annotations

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))

`convert(text, md)`

Convert text to Markdown.

Parameters:

Type	Description	Default
[`str`][]	The text to convert.	required
`Markdown`{ .external title="markdown.Markdown" }	A Markdown instance.	required

Returns:

Type	Name	Description
`Markup`{ .external title="markupsafe.Markup" }	`text`	Converted markup.
////

//// tab | Source annotations

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))

`convert(text, md)`

Convert text to Markdown.

Parameters:

Type	Description	Default
[`str`][]	The text to convert.	required
`markdown.Markdown`	A Markdown instance.	required

Returns:

Type	Name	Description
`Markup`{ .external title="markupsafe.Markup" }	`text`	Converted markup.
////

//// tab | Full annotations

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))

`convert(text, md)`

Convert text to Markdown.

Parameters:

Type	Description	Default
[`str`][]	The text to convert.	required
`markdown.Markdown`	A Markdown instance.	required

Returns:

Type	Name	Description
`markupsafe.Markup`	`text`	Converted markup.
////
///

{#option-line_length}

`line_length`

:octicons-package-24: Type [int][] :material-equal: 60{ title="default value" }

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 a formatter and the specified line length.

The handler will automatically try to format using :

[Black]
[Ruff]

If a formatter is not found, 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

/// admonition | Preview type: preview

//// tab | Line length 60

long_function_name

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

////

//// tab | Line length 80

long_function_name

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

//// ///

{#option-modernize_annotations}

`modernize_annotations`

:octicons-heart-fill-24:{ .pulse } Sponsors only{ .insiders } — :octicons-tag-24: Insiders 1.8.0 — This feature also requires Griffe Insiders to be installed.

:octicons-package-24: Type [bool][] :material-equal: False{ title="default value" }

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

/// admonition | Preview type: preview

--8<-- "docs/snippets/package/modern.py"

//// tab | Unchanged annotations

::: package.modern.example
    options:
      modernize_annotations: false
      show_symbol_type_heading: false
      show_labels: false

////

//// tab | Modernized annotations

::: package.modern.example
    options:
      modernize_annotations: true
      show_symbol_type_heading: false
      show_labels: false

////

///

{#option-show_signature}

`show_signature`

:octicons-package-24: Type [bool][] :material-equal: True{ title="default value" }

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

/// admonition | Preview type: preview

//// tab | With signature

`function(param1, param2=None)`

Function docstring.

////

//// tab | Without signature

`function`

Function docstring.

//// ///

{#option-show_signature_annotations}

`show_signature_annotations`

:octicons-package-24: Type [bool][] :material-equal: False{ title="default value" }

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][separate_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

/// admonition | Preview type: preview

//// tab | With signature annotations

function

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

Function docstring.

////

//// tab | Without signature annotations

function

function(param1, param2=None)

Function docstring.

//// ///

{#option-separate_signature}

`separate_signature`

:octicons-package-24: Type [bool][] :material-equal: False{ title="default value" }

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 a formatter and the specified [line length][line_length].

The handler will automatically try to format using :

[Black]
[Ruff]

If a formatter is not found, the handler issues an INFO log once.

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

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

/// admonition | Preview type: preview

//// tab | With separate signature

function

function(param1, param2=None)

Function docstring.

////

//// tab | Without separate signature

`function(param1, param2=None)`

Function docstring.

//// ///

{#option-show_overloads}

`show_overloads`

Whether to render function / method overloads.

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

::: path.to.module
    options:
      show_overloads: false

/// admonition | Preview type: preview //// tab | With overloads

function

@overload
function(param1: int): ...

@overload
function(param1: str): ...

function(param1: str | int)

Function docstring.

//// //// tab | Without overloads

function

function(param1: str | int)

Function docstring.

//// ///

{#option-signature_crossrefs}

`signature_crossrefs`

:octicons-tag-24: 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

/// admonition | Preview type: preview

//// tab | With signature cross-references

do_format_code

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

Function docstring.

////

//// tab | Without signature cross-references

do_format_code

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

Function docstring.

//// ///

{#option-unwrap_annotated}

`unwrap_annotated`

:octicons-package-24: Type [bool][] :material-equal: False{ title="default value" }

Whether to unwrap Annotated{ .external } 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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

signatures.md

signatures.md

Signatures options

`annotations_path`

`convert(text, md)`

`convert(text, md)`

`convert(text, md)`

`line_length`

long_function_name

long_function_name

`modernize_annotations`

`show_signature`

`function(param1, param2=None)`

`function`

`show_signature_annotations`

function

function

`separate_signature`

function

`function(param1, param2=None)`

`show_overloads`

function

function

`signature_crossrefs`

do_format_code

do_format_code

`unwrap_annotated`

Files

signatures.md

Latest commit

History

signatures.md

File metadata and controls

Signatures options

annotations_path

convert(text, md)

convert(text, md)

convert(text, md)

line_length

long_function_name

long_function_name

modernize_annotations

show_signature

function(param1, param2=None)

function

show_signature_annotations

function

function

separate_signature

function

function(param1, param2=None)

show_overloads

function

function

signature_crossrefs

do_format_code

do_format_code

unwrap_annotated

`annotations_path`

`convert(text, md)`

`convert(text, md)`

`convert(text, md)`

`line_length`

`modernize_annotations`

`show_signature`

`function(param1, param2=None)`

`function`

`show_signature_annotations`

`separate_signature`

`function(param1, param2=None)`

`show_overloads`

`signature_crossrefs`

`unwrap_annotated`