Skip to content

Docstrings options¤

docstring_style¤

  • Type str "google"

The docstring style to expect when parsing docstrings.

Possible values:

in mkdocs.yml (global configuration)
plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          docstring_style: google
or in docs/some_page.md (local configuration)
::: path.to.module
    options:
      docstring_style: numpy

Preview

Every style gets rendered the same way. Here are some docstring examples.

def greet(name: str) -> str:
    """Greet someone.

    Parameters:
        name: The name of the person to greet.

    Returns:
        A greeting message.
    """
    return f"Hello {name}!"
def greet(name: str) -> str:
    """Greet someone.

    Parameters
    ----------
    name
        The name of the person to greet.

    Returns
    -------
    A greeting message.
    """
    return f"Hello {name}!"
def greet(name: str) -> str:
    """Greet someone.

    :param name: The name of the person to greet.
    :return: A greeting message.
    """
    return f"Hello {name}!"

docstring_options¤

The options for the docstring parser.

The Sphinx style does not offer any option.

in mkdocs.yml (global configuration)
plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          docstring_options:
            ignore_init_summary: false
            trim_doctest_flags: true
or in docs/some_page.md (local configuration)
::: path.to.module
    options:
      docstring_options:
        ignore_init_summary: true
        trim_doctest_flags: false
class PrintOK:
    """Class docstring."""

    def __init__(self):
        """Initialize the instance.

        Examples:
            >>> Class()  # doctest: +NORMALIZE_WHITESPACE
            ok
        """
        print("ok")

Preview

PrintOK

Class docstring.

__init__

Examples:

>>> Class()
ok

PrintOK

Class docstring.

__init__

Initialize the instance.

Examples:

>>> Class()  # doctest: +NORMALIZE_WHITESPACE
ok

docstring_section_style¤

  • Type str "table"

The style used to render docstring sections.

A section is a block of text that has a special meaning in a docstring. There are sections for documenting attributes of an object, parameters of a function, exceptions raised by a function, the return value of a function, etc.

Sections are parsed as structured data and can therefore be rendered in different ways. Possible values:

  • "table": a simple table, usually with type, name and description columns
  • "list": a simple list, akin to what you get with the ReadTheDocs Sphinx theme
  • "spacy": a poor implementation of the amazing tables in Spacy's documentation
in mkdocs.yml (global configuration)
plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          docstring_section_style: table
or in docs/some_page.md (local configuration)
::: path.to.module
    options:
      docstring_section_style: list

Preview

Tables work well when you have lots of items with short names, type annotations, descriptions, etc.. With longer strings, the columns risk getting squished horizontally. In that case, the Spacy tables can help.

Parameters:

Type Name Description Default
int threshold Threshold for something. required
bool flag Enable something. False

Other Parameters:

Type Name Description Default
list[int | float] gravity_forces Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. required
VacuumType | Literal["regular"] vacuum_type Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. VacuumType.PLASMA

Lists work well whatever the length of names, type annotations, descriptions, etc.

Parameters:

  • threshold (int) — Threshold for something.
  • flag (bool) — Enable something.

Other Parameters:

  • gravity_forces (list[int | float]) — Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
  • vacuum_type (VacuumType | Literal["regular"]) — Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Spacy tables work better than regular tables with longer names, type annotations, descriptions, etc., by reserving more horizontal space on the second column.

Parameters:

Name Description
threshold Threshold for something.
TYPE: int DEFAULT: required
flag Enable something.
TYPE: bool DEFAULT: False

Other Parameters:

Name Description
gravity_forces Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
TYPE: list[int | float] DEFAULT: required
vacuum_type Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
TYPE:VacuumType | Literal["regular"] DEFAULT: VacuumType.PLASMA

merge_init_into_class¤

Whether to merge the __init__ method into the class' signature and docstring.

By default, only the class name is rendered in headings. When merging, the __init__ method parameters are added after the class name, like a signature, and the __init__ method docstring is appended to the class' docstring. This option is well used in combination with the ignore_init_summary docstring option, to discard the first line of the __init__ docstring which is not often useful.

in mkdocs.yml (global configuration)
plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          docstring_options:
            ignore_init_summary: false
          merge_init_into_class: false
or in docs/some_page.md (local configuration)
::: path.to.module
    options:
      docstring_options:
        ignore_init_summary: true
      merge_init_into_class: true
class Thing:
    """A class for things."""

    def __init__(self, value: int = 0):
        """Initialize a thing.

        Parameters:
            value: The thing's value.
        """
        self.value = value

Preview

Thing(value=0)

Class docstring.

Parameters:

Type Name Description Default
int value The thing's value. 0

Thing

Class docstring.

__init__(value=0)

Initialize a thing.

Parameters:

Type Name Description Default
int value The thing's value. 0

show_if_no_docstring¤

Show the object heading even if it has no docstring or children with docstrings.

Without an explicit list of members, members are selected based on filters, and then filtered again to keep only those with docstrings. Checking if a member has a docstring is done recursively: if at least one of its direct or indirect members (lower in the tree) has a docstring, the member is rendered. If the member does not have a docstring, and none of its members have a docstring, it is excluded.

With this option you can tell the Python handler to skip the docstring check.

in mkdocs.yml (global configuration)
plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          show_if_no_docstring: false
or in docs/some_page.md (local configuration)
::: path.to.module
    options:
      show_if_no_docstring: true
def function_without_docstring():
    ...


def function_with_docstring():
    """Hello."""


class ClassWithoutDocstring:
    def method_without_docstring(self):
        ...

    def method_with_docstring(self):
        """Hello."""

Preview

function_without_docstring

function_with_docstring

Hello.

ClassWithoutDocstring

method_without_docstring

method_with_docstring

Hello.

function_with_docstring

Hello.

ClassWithoutDocstring

method_with_docstring

Hello.

show_docstring_attributes¤

Whether to render the "Attributes" sections of docstrings.

in mkdocs.yml (global configuration)
plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          show_docstring_attributes: true
or in docs/some_page.md (local configuration)
::: path.to.module
    options:
      show_docstring_attributes: false
class Class:
    """Summary.

    Attributes:
        attr: Some attribute.
    """

    attr: int = 1

Preview

Class

Summary.

Attributes:

Type Name Description
int attr Some attribute.

Class

Summary.

show_docstring_functions¤

Whether to render the "Functions" or "Methods" sections of docstrings.

in mkdocs.yml (global configuration)
plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          show_docstring_functions: true
or in docs/some_page.md (local configuration)
::: path.to.module
    options:
      show_docstring_functions: false
"""Summary.

Functions:
    foo: Some function.
"""


def foo():
    ...


class Class:
    """Summary.

    Methods:
        bar: Some method.
    """

    def bar(self):
        ...

Preview

module

Summary.

Functions:

Name Description
foo Some function.

Class

Summary.

Methods:

Name Description
bar Some method.

module

Summary.

Class

Summary.

show_docstring_classes¤

Whether to render the "Classes" sections of docstrings.

in mkdocs.yml (global configuration)
plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          show_docstring_classes: true
or in docs/some_page.md (local configuration)
::: path.to.module
    options:
      show_docstring_classes: false
"""Summary.

Classes:
    Class: Some class.
"""


class Class:
    """Summary."""

Preview

module

Summary.

Classes:

Name Description
Class Some class.

Class

Summary.

module

Summary.

Class

Summary.

show_docstring_modules¤

Whether to render the "Modules" sections of docstrings.

in mkdocs.yml (global configuration)
plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          show_docstring_modules: true
or in docs/some_page.md (local configuration)
::: path.to.module
    options:
      show_docstring_modules: false
📁 module/
├── 📄 __init__.py
└── 📄 submodule.py
module/__init__.py
"""Summary.

Modules:
    submodule: Some module.
"""

Preview

module

Summary.

Modules:

Name Description
submodule Some module.

module

Summary.

show_docstring_description¤

Whether to render the textual blocks (including admonitions) of docstrings.

in mkdocs.yml (global configuration)
plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          show_docstring_description: true
or in docs/some_page.md (local configuration)
::: path.to.module
    options:
      show_docstring_description: false
class Class:
    """Summary.

    Long description.

    Warning: Deprecated
        Stop using this class.

    Attributes:
        attr: Some attribute.
    """

    attr: int = 1

Preview

Class

Summary.

Long description.

Deprecated

Stop using this class.

Attributes:

Type Name Description
int attr Some attribute.

Class

Attributes:

Type Name Description
int attr Some attribute.

show_docstring_examples¤

Whether to render the "Examples" section of docstrings.

in mkdocs.yml (global configuration)
plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          show_docstring_examples: true
or in docs/some_page.md (local configuration)
::: path.to.module
    options:
      show_docstring_examples: false
def print_hello():
    """Print hello.

    Examples:
        >>> print("hello")
        hello
    """
    print("hello")

Preview

print_hello

Print hello.

Examples:

>>> print("hello")
hello

print_hello

Print hello.

show_docstring_other_parameters¤

Whether to render the "Other Parameters" section of docstrings.

in mkdocs.yml (global configuration)
plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          show_docstring_other_parameters: true
or in docs/some_page.md (local configuration)
::: path.to.module
    options:
      show_docstring_other_parameters: false
def do_something(**kwargs):
    """Do something.

    Other parameters:
        whatever (int): Some integer.
    """

Preview

do_something

Do something.

Other parameters:

Type Name Description
int whatever Some integer.

do_something

Do something.

show_docstring_parameters¤

Whether to render the "Parameters" section of docstrings.

in mkdocs.yml (global configuration)
plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          show_docstring_parameters: true
or in docs/some_page.md (local configuration)
::: path.to.module
    options:
      show_docstring_parameters: false
def do_something(whatever: int = 0):
    """Do something.

    Parameters:
        whatever: Some integer.
    """

Preview

do_something

Do something.

Parameters:

Type Name Description Default
int whatever Some integer. 0

do_something

Do something.

show_docstring_raises¤

Whether to render the "Raises" section of docstrings.

in mkdocs.yml (global configuration)
plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          show_docstring_raises: true
or in docs/some_page.md (local configuration)
::: path.to.module
    options:
      show_docstring_raises: false
def raise_runtime_error():
    """Raise a runtime error.

    Raises:
        RuntimeError: Not good.
    """
    raise RuntimeError

Preview

raise_runtime_error

Raise a runtime error.

Raises:

Type Description
RuntimeError Not good.

raise_runtime_error

Raise a runtime error.

show_docstring_receives¤

Whether to render the "Receives" section of docstrings.

in mkdocs.yml (global configuration)
plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          show_docstring_receives: true
or in docs/some_page.md (local configuration)
::: path.to.module
    options:
      show_docstring_receives: false
def iter_skip(
    iterable: Iterable[T],
    initial_skip: int = 0,
) -> Generator[T, int, None]:
    """Iterate and skip elements.

    Receives:
        skip: Number of elements to skip.
    """
    skip = initial_skip
    for element in iterable:
        if skip or 0 > 0:
            skip -= 1
        else:
            skip = yield element

Preview

iter_skip

Iterate and skip elements.

Receives:

Type Description
int Number of elements to skip.

iter_skip

Iterate and skip elements.

show_docstring_returns¤

Whether to render the "Returns" section of docstrings.

in mkdocs.yml (global configuration)
plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          show_docstring_returns: true
or in docs/some_page.md (local configuration)
::: path.to.module
    options:
      show_docstring_returns: false
def rand() -> int:
    """Return a random number.

    Returns:
        A random number.
    """
    return random.randint(0, 1000)

Preview

rand

Return a random number.

Returns:

Type Description
int A random number.

rand

Return a random number.

show_docstring_warns¤

Whether to render the "Warns" section of docstrings.

in mkdocs.yml (global configuration)
plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          show_docstring_warns: true
or in docs/some_page.md (local configuration)
::: path.to.module
    options:
      show_docstring_warns: false
def warn():
    """Warn user.

    Warns:
        UserWarning: When this is inappropriate.
    """
    warnings.warn(UserWarning("This is inappropriate"))

Preview

warn

Warn user.

Warns:

Type Description
UserWarning When this is inappropriate.

warn

Warn user.

show_docstring_yields¤

Whether to render the "Yields" section of docstrings.

in mkdocs.yml (global configuration)
plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          show_docstring_yields: true
or in docs/some_page.md (local configuration)
::: path.to.module
    options:
      show_docstring_yields: false
def iter_skip(
    iterable: Iterable[T],
    initial_skip: int = 0,
) -> Generator[T, int, None]:
    """Iterate and skip elements.

    Yields:
        Elements of the iterable.
    """
    skip = initial_skip
    for element in iterable:
        if skip or 0 > 0:
            skip -= 1
        else:
            skip = yield element

Preview

iter_skip

Iterate and skip elements.

Yields:

Type Description
T Elements of the iterable.

iter_skip

Iterate and skip elements.