Docstrings options¤

docstring_style¤

• Type str "google"

The docstring style to expect when parsing docstrings.

Possible values:

• "google": see Google style.
• "numpy": see Numpy style.
• "sphinx": see Sphinx style.
• None (null or ~ in YAML): no style at all, parse as regular text.

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          docstring_style: google

::: path.to.module
    options:
      docstring_style: numpy

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¤

• Type dict {}

The options for the docstring parser.

• Google-style options
• Numpydoc-style options

The Sphinx style does not offer any option.

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          docstring_options:
            ignore_init_summary: false
            trim_doctest_flags: true

::: 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:
            >>> PrintOK()  # doctest: +NORMALIZE_WHITESPACE
            ok
        """
        print("ok")

>>> PrintOK()
ok

>>> PrintOK()  # 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

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          docstring_section_style: table

::: path.to.module
    options:
      docstring_section_style: list

merge_init_into_class¤

• Type bool False

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.

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          docstring_options:
            ignore_init_summary: false
          merge_init_into_class: false

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

relative_crossrefs¤

Sponsors only — Insiders 1.9.0

• Type bool False

Whether to enable the relative-crossref syntax.

The relative-crossref syntax lets you reference the current object or its parent by prefixing a crossref identifier with dots. For example, to cross-reference the current object's name member, you can write [link to name attribute][.name]. The "current object" is the object containing the docstring being rendered.

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

::: path.to.module
    options:
      relative_crossrefs: true

"""Summary.

- Link to [`module`][.].
- Link to [`module_attribute`][.module_attribute].
- Link to [`Class`][.Class].
- Link to [`class_attribute`][.Class.class_attribute].
- Link to [`instance_attribute`][.Class.instance_attribute].
- Link to [`method`][.Class.method].
"""

module_attribute = 0
"""Summary.

- Link to [`module`][..].
- Link to [`module_attribute`][.].
- Link to [`Class`][..Class].
- Link to [`class_attribute`][..Class.class_attribute].
- Link to [`instance_attribute`][..Class.instance_attribute].
- Link to [`method`][..Class.method].
"""

class Class:
    """Summary.

    - Link to [`module`][..].
    - Link to [`module_attribute`][..module_attribute].
    - Link to [`Class`][.].
    - Link to [`class_attribute`][.class_attribute].
    - Link to [`instance_attribute`][.instance_attribute].
    - Link to [`method`][.method].
    """

    class_attribute = 0
    """Summary.

    - Link to [`module`][...].
    - Link to [`module_attribute`][...module_attribute].
    - Link to [`Class`][..].
    - Link to [`class_attribute`][.].
    - Link to [`instance_attribute`][..instance_attribute].
    - Link to [`method`][..method].
    """

    def __init__(self):
        """Summary.

        - Link to [`module`][...].
        - Link to [`module_attribute`][...module_attribute].
        - Link to [`Class`][..].
        - Link to [`class_attribute`][..class_attribute].
        - Link to [`instance_attribute`][..instance_attribute].
        - Link to [`method`][..method].
        """
        self.instance_attribute = 0
        """Summary.

        - Link to [`module`][...].
        - Link to [`module_attribute`][...module_attribute].
        - Link to [`Class`][..].
        - Link to [`class_attribute`][..class_attribute].
        - Link to [`instance_attribute`][.].
        - Link to [`method`][..method].
        """

    def method(self):
        """Summary.

        - Link to [`module`][...].
        - Link to [`module_attribute`][...module_attribute].
        - Link to [`Class`][..].
        - Link to [`class_attribute`][..class_attribute].
        - Link to [`instance_attribute`][..instance_attribute].
        - Link to [`method`][.].
        """

scoped_crossrefs¤

Sponsors only — Insiders 1.9.0

• Type bool False

Whether to enable scoped cross-references.

With scoped cross-references, you can write identifiers as if you wanted to access them from the current object's scope. The scoping rules do not exactly match Python's: you can reference members and siblings too, without prefixing with self. or cls..

The following order is applied when resolving a name in a given scope:

1. member of the current object
2. parent class
3. repeat 1-2 within parent's scope

In practice, it means that the name is first looked up in members, then it is compared against the parent name (only if it's a class), then it is looked up in siblings. It continues climbing up the object tree until there's no parent, in which case it raises a name resolution error.

Cross-referencing an imported object will directly link to this object if the objects inventory of the project it comes from was loaded. You won't be able to cross-reference it within your own documentation with scoped references, if you happen to be rendering this external object too. In that case, you can use an absolute reference or a relative one instead.

Another limitation is that you won't be able to reference an external package if its name can be resolved in the current object's scope.

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

::: path.to.module
    options:
      scoped_crossrefs: true

"""Summary.

- Link to [`module_attribute`][module_attribute].
- Link to [`Class`][Class].
- Link to [`class_attribute`][Class.class_attribute].
- Link to [`instance_attribute`][Class.instance_attribute].
- Link to [`method`][Class.method].
"""

module_attribute = 0
"""Summary.

- Link to [`Class`][Class].
- Link to [`class_attribute`][Class.class_attribute].
- Link to [`instance_attribute`][Class.instance_attribute].
- Link to [`method`][Class.method].
"""

class Class:
    """Summary.

    - Link to [`module_attribute`][module_attribute].
    - Link to [`class_attribute`][class_attribute].
    - Link to [`instance_attribute`][instance_attribute].
    - Link to [`method`][method].
    """

    class_attribute = 0
    """Summary.

    - Link to [`module_attribute`][module_attribute].
    - Link to [`Class`][Class].
    - Link to [`instance_attribute`][instance_attribute].
    - Link to [`method`][method].
    """

    def __init__(self):
        """Summary.

        - Link to [`module_attribute`][module_attribute].
        - Link to [`Class`][Class].
        - Link to [`class_attribute`][class_attribute].
        - Link to [`instance_attribute`][instance_attribute].
        - Link to [`method`][method].
        """
        self.instance_attribute = 0
        """Summary.

        - Link to [`module_attribute`][module_attribute].
        - Link to [`Class`][Class].
        - Link to [`class_attribute`][class_attribute].
        - Link to [`method`][method].
        """

    def method(self):
        """Summary.

        - Link to [`module_attribute`][module_attribute].
        - Link to [`Class`][Class].
        - Link to [`class_attribute`][class_attribute].
        - Link to [`instance_attribute`][instance_attribute].
        """

show_if_no_docstring¤

• Type bool False

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.

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

::: 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."""

show_docstring_attributes¤

• Type bool True

Whether to render the "Attributes" sections of docstrings.

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

::: path.to.module
    options:
      show_docstring_attributes: false

class Class:
    """Summary.

    Attributes:
        attr: Some attribute.
    """

    attr: int = 1

show_docstring_functions¤

• Type bool True

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

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

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

show_docstring_classes¤

• Type bool True

Whether to render the "Classes" sections of docstrings.

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

::: path.to.module
    options:
      show_docstring_classes: false

"""Summary.

Classes:
    Class: Some class.
"""


class Class:
    """Summary."""

show_docstring_modules¤

• Type bool True

Whether to render the "Modules" sections of docstrings.

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

::: path.to.module
    options:
      show_docstring_modules: false

📁 module/
├──  __init__.py
└──  submodule.py

"""Summary.

Modules:
    submodule: Some module.
"""

show_docstring_description¤

• Type bool True

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

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

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

show_docstring_examples¤

• Type bool True

Whether to render the "Examples" section of docstrings.

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

::: path.to.module
    options:
      show_docstring_examples: false

def print_hello():
    """Print hello.

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

>>> print("hello")
hello

show_docstring_other_parameters¤

• Type bool True

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

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

::: path.to.module
    options:
      show_docstring_other_parameters: false

def do_something(**kwargs):
    """Do something.

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

show_docstring_parameters¤

• Type bool True

Whether to render the "Parameters" section of docstrings.

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

::: path.to.module
    options:
      show_docstring_parameters: false

def do_something(whatever: int = 0):
    """Do something.

    Parameters:
        whatever: Some integer.
    """

show_docstring_raises¤

• Type bool True

Whether to render the "Raises" section of docstrings.

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

::: path.to.module
    options:
      show_docstring_raises: false

def raise_runtime_error():
    """Raise a runtime error.

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

show_docstring_receives¤

• Type bool True

Whether to render the "Receives" section of docstrings.

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

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

show_docstring_returns¤

• Type bool True

Whether to render the "Returns" section of docstrings.

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

::: path.to.module
    options:
      show_docstring_returns: false

def rand() -> int:
    """Return a random number.

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

show_docstring_warns¤

• Type bool True

Whether to render the "Warns" section of docstrings.

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

::: path.to.module
    options:
      show_docstring_warns: false

def warn():
    """Warn user.

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

show_docstring_yields¤

• Type bool True

Whether to render the "Yields" section of docstrings.

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

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