Docstrings options

`docstring_style`

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

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

/// admonition | Preview type: preview

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

//// tab | Google

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

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

    Returns:
        A greeting message.
    """
    return f"Hello {name}!"

////

//// tab | 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}!"

////

//// tab | Sphinx

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`

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

The options for the docstring parser.

Google-style options{ .external }
Numpydoc-style options{ .external }

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

/// admonition | Preview type: preview

//// tab | Ignore init summary, trim doctest flags

`PrintOK`

Class docstring.

`init`

Examples:

>>> PrintOK()
ok

////

//// tab | Keep init summary and doctest flags

`PrintOK`

Class docstring.

`init`

Initialize the instance.

Examples:

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

//// ///

`docstring_section_style`

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

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]{ .external }
"spacy": a poor implementation of the amazing tables in [Spacy's documentation]{ .external }

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

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

/// admonition | Preview type: preview

//// tab | Table 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`
////

//// tab | List 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. ////

//// tab | Spacy 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`

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

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][docstring_options], 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

/// admonition | Preview type: preview

//// tab | Merged, summary discarded

`Thing(value=0)`

Class docstring.

Parameters:

Type	Name	Description	Default
[`int`][]	`value`	The thing's value.	`0`
////

//// tab | Unmerged, summary kept

`Thing`

Class docstring.

`init(value=0)`

Initialize a thing.

Parameters:

Type	Name	Description	Default
[`int`][]	`value`	The thing's value.	`0`
////
///

`relative_crossrefs`

:octicons-heart-fill-24:{ .pulse } Sponsors only{ .insiders } — :octicons-tag-24: Insiders 1.9.0

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

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

/// admonition | Examples type: preview

"""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`][.].
        """

///

INFO: There is an alternative, third-party Python handler that handles relative references: mkdocstrings-python-xref.

`scoped_crossrefs`

:octicons-heart-fill-24:{ .pulse } Sponsors only{ .insiders } — :octicons-tag-24: Insiders 1.9.0

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

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:

member of the current object
parent class
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][import]. 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][relative_crossrefs] 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

/// admonition | Examples type: preview

"""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`

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

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

/// admonition | Preview type: preview

//// tab | Show

`function_without_docstring`

`function_with_docstring`

Hello.

`ClassWithoutDocstring`

`method_without_docstring`

`method_with_docstring`

Hello.

////

//// tab | Don't show

`function_with_docstring`

Hello.

`ClassWithoutDocstring`

`method_with_docstring`

Hello.

//// ///

`show_docstring_attributes`

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

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

/// admonition | Preview type: preview

//// tab | With attributes

`Class`

Summary.

Attributes:

Type	Name	Description
[`int`][]	`attr`	Some attribute.
////

//// tab | Without attributes

`Class`

Summary.

//// ///

`show_docstring_functions`

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

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

/// admonition | Preview type: preview

//// tab | With functions

module

Summary.

Functions:

Name	Description
`foo`	Some function.

`Class`

Summary.

Methods:

Name	Description
`bar`	Some method.
////

//// tab | Without functions

module

Summary.

`Class`

Summary.

//// ///

`show_docstring_classes`

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

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

/// admonition | Preview type: preview

//// tab | With classes

module

Summary.

Classes:

Name	Description
`Class`	Some class.

`Class`

Summary.

////

//// tab | Without classes

module

Summary.

`Class`

Summary.

//// ///

`show_docstring_type_aliases`

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

Whether to render the "Type Aliases" sections of docstrings.

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

::: path.to.module
    options:
      show_docstring_type_aliases: false

"""Summary.

Type Aliases:
    TypeAlias: Some type alias.
"""


type TypeAlias = int
"""Summary."""

/// admonition | Preview type: preview

//// tab | With type_aliases

module

Summary.

Type Aliases:

Name	Description
`TypeAlias`	Some type alias.

`TypeAlias`

Summary.

////

//// tab | Without classes

module

Summary.

`TypeAlias`

Summary.

//// ///

`show_docstring_modules`

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

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

/// admonition | Preview type: preview

//// tab | With modules

module

Summary.

Modules:

Name	Description
`submodule`	Some module.

////

//// tab | Without modules

module

Summary.

//// ///

`show_docstring_description`

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

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

/// admonition | Preview type: preview

//// tab | With description blocks

`Class`

Summary.

Long description.

Deprecated

Stop using this class.

Attributes:

Type	Name	Description
[`int`][]	`attr`	Some attribute.
////

//// tab | Without description blocks

`Class`

Attributes:

Type	Name	Description
[`int`][]	`attr`	Some attribute.
////
///

`show_docstring_examples`

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

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

/// admonition | Preview type: preview

//// tab | With examples

`print_hello`

Print hello.

Examples:

>>> print("hello")
hello

////

//// tab | Without examples

`print_hello`

Print hello.

//// ///

`show_docstring_other_parameters`

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

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

/// admonition | Preview type: preview

//// tab | With other parameters

`do_something`

Do something.

Other parameters:

Type	Name	Description
[`int`][]	`whatever`	Some integer.
////

//// tab | Without other parameters

`do_something`

Do something.

//// ///

`show_docstring_parameters`

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

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

/// admonition | Preview type: preview

//// tab | With parameters

`do_something`

Do something.

Parameters:

Type	Name	Description	Default
[`int`][]	`whatever`	Some integer.	`0`
////

//// tab | Without parameters

`do_something`

Do something.

//// ///

`show_docstring_raises`

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

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

/// admonition | Preview type: preview

//// tab | With exceptions

`raise_runtime_error`

Raise a runtime error.

Raises:

Type	Description
[`RuntimeError`][]	Not good.
////

//// tab | Without exceptions

`raise_runtime_error`

Raise a runtime error.

//// ///

`show_docstring_receives`

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

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

/// admonition | Preview type: preview

//// tab | With received values

`iter_skip`

Iterate and skip elements.

Receives:

Type	Description
[`int`][]	Number of elements to skip.
////

//// tab | Without received values

`iter_skip`

Iterate and skip elements.

//// ///

`show_docstring_returns`

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

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)

/// admonition | Preview type: preview

//// tab | With return value

`rand`

Return a random number.

Returns:

Type	Description
[`int`][]	A random number.
////

//// tab | Without return value

`rand`

Return a random number.

//// ///

`show_docstring_type_parameters`

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

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

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

::: path.to.module
    options:
      show_docstring_type_parameters: false

class AClass[X: (int, str) = str]:
    """Represents something.

    Type Parameters:
        X: Something.
    """

/// admonition | Preview type: preview

//// tab | With parameters

`AClass`

Represents something.

Type Parameters:

Name	Bound or Constraints	Description	Default
`whatever`	`(int, str)`	Something.	`str`
////

//// tab | Without parameters

`AClass`

Represents something.

//// ///

`show_docstring_warns`

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

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

/// admonition | Preview type: preview

//// tab | With warnings

`warn`

Warn user.

Warns:

Type	Description
[`UserWarning`][]	When this is inappropriate.
////

//// tab | Without warnings

`warn`

Warn user.

//// ///

`show_docstring_yields`

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

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

/// admonition | Preview type: preview

//// tab | With yielded values

`iter_skip`

Iterate and skip elements.

Yields:

Type	Description
`T`	Elements of the iterable.
////

//// tab | Without yielded values

`iter_skip`

Iterate and skip elements.

//// ///

Files

docstrings.md

Latest commit

History

docstrings.md

File metadata and controls

Docstrings options

docstring_style

docstring_options

PrintOK

__init__

PrintOK

__init__

docstring_section_style

merge_init_into_class

Thing(value=0)

Thing

__init__(value=0)

relative_crossrefs

scoped_crossrefs

show_if_no_docstring

function_without_docstring

function_with_docstring

ClassWithoutDocstring

method_without_docstring

method_with_docstring

function_with_docstring

ClassWithoutDocstring

method_with_docstring

show_docstring_attributes

Class

Class

show_docstring_functions

module

Class

module

Class

show_docstring_classes

module

Class

module

Class

show_docstring_type_aliases

module

TypeAlias

module

TypeAlias

show_docstring_modules

module

module

show_docstring_description

Class

Class

show_docstring_examples

print_hello

print_hello

show_docstring_other_parameters

do_something

do_something

show_docstring_parameters

do_something

do_something

show_docstring_raises

raise_runtime_error

raise_runtime_error

show_docstring_receives

iter_skip

iter_skip

show_docstring_returns

rand

rand

show_docstring_type_parameters

AClass

AClass

show_docstring_warns

warn

warn

show_docstring_yields

iter_skip

iter_skip

`docstring_style`

`docstring_options`

`PrintOK`

`init`

`PrintOK`

`init`

`docstring_section_style`

`merge_init_into_class`

`Thing(value=0)`

`Thing`

`init(value=0)`

`relative_crossrefs`

`scoped_crossrefs`

`show_if_no_docstring`

`function_without_docstring`

`function_with_docstring`

`ClassWithoutDocstring`

`method_without_docstring`

`method_with_docstring`

`function_with_docstring`

`ClassWithoutDocstring`

`method_with_docstring`

`show_docstring_attributes`

`Class`

`Class`

`show_docstring_functions`

`Class`

`Class`

`show_docstring_classes`

`Class`

`Class`

`show_docstring_type_aliases`

`TypeAlias`

`TypeAlias`

`show_docstring_modules`

`show_docstring_description`

`Class`

`Class`

`show_docstring_examples`

`print_hello`

`print_hello`

`show_docstring_other_parameters`

`do_something`

`do_something`

`show_docstring_parameters`

`do_something`

`do_something`

`show_docstring_raises`

`raise_runtime_error`

`raise_runtime_error`

`show_docstring_receives`

`iter_skip`

`iter_skip`

`show_docstring_returns`

`rand`

`rand`

`show_docstring_type_parameters`

`AClass`

`AClass`

`show_docstring_warns`

`warn`

`warn`

`show_docstring_yields`

`iter_skip`

`iter_skip`