PrintOKClass docstring.
__init__Examples:
```pycon >>> PrintOK() ok ``` //// //// tab | Keep init summary and doctest flagsPrintOKClass docstring.
__init__Initialize the instance.
Examples:
```pycon >>> PrintOK() # doctest: +NORMALIZE_WHITESPACE ok ``` //// /// [](){#option-docstring_section_style} ## `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 } ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: docstring_section_style: table ``` ```md title="or in docs/some_page.md (local configuration)" ::: 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 ]VacuumType \| Literal ["regular"]list [int \| float ]VacuumType \| Literal ["regular"]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.list [int \| float ]VacuumType \| Literal ["regular"]VacuumType.PLASMA
////
///
[](){#option-merge_init_into_class}
## `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.
```yaml title="in mkdocs.yml (global configuration)"
plugins:
- mkdocstrings:
handlers:
python:
options:
docstring_options:
ignore_init_summary: false
merge_init_into_class: false
```
```md title="or in docs/some_page.md (local configuration)"
::: path.to.module
options:
docstring_options:
ignore_init_summary: true
merge_init_into_class: true
```
```python
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 keptThingClass docstring.
__init__(value=0)Initialize a thing.
Parameters:
**Type** | **Name** | **Description** | **Default** --------- | -------- | ------------------ | ----------- [`int`][] | `value` | The thing's value. | `0` //// /// [](){#option-relative_crossrefs} ## `relative_crossrefs` [:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } — [:octicons-tag-24: Insiders 1.9.0](../../insiders/changelog.md#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. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: relative_crossrefs: false ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: relative_crossrefs: true ``` /// admonition | Examples type: preview ```python title="pkg/module.py" """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](https://github.com/analog-garage/mkdocstrings-python-xref).** [](){#option-scoped_crossrefs} ## `scoped_crossrefs` [:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } — [:octicons-tag-24: Insiders 1.9.0](../../insiders/changelog.md#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: 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][inventories]. 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. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: scoped_crossrefs: false ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: scoped_crossrefs: true ``` /// admonition | Examples type: preview ```python title="pkg/module.py" """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]. """ ``` /// [](){#option-show_if_no_docstring} ## `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. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_if_no_docstring: false ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: show_if_no_docstring: true ``` ```python 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 | Showfunction_without_docstringfunction_with_docstringHello.
ClassWithoutDocstringmethod_without_docstringmethod_with_docstringHello.
//// //// tab | Don't showfunction_with_docstringHello.
ClassWithoutDocstringmethod_with_docstringHello.
//// /// [](){#option-show_docstring_attributes} ## `show_docstring_attributes` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Whether to render the "Attributes" sections of docstrings. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_docstring_attributes: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: show_docstring_attributes: false ``` ```python class Class: """Summary. Attributes: attr: Some attribute. """ attr: int = 1 ``` /// admonition | Preview type: preview //// tab | With attributesClassSummary.
Attributes:
**Type** | **Name** | **Description** --------- | -------- | --------------- [`int`][] | `attr` | Some attribute. //// //// tab | Without attributesClassSummary.
//// /// [](){#option-show_docstring_functions} ## `show_docstring_functions` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Whether to render the "Functions" or "Methods" sections of docstrings. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_docstring_functions: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: show_docstring_functions: false ``` ```python """Summary. Functions: foo: Some function. """ def foo(): ... class Class: """Summary. Methods: bar: Some method. """ def bar(self): ... ``` /// admonition | Preview type: preview //// tab | With functionsSummary.
Functions:
**Name** | **Description** -------- | --------------- `foo` | Some function.ClassSummary.
Methods:
**Name** | **Description** -------- | --------------- `bar` | Some method. //// //// tab | Without functionsSummary.
ClassSummary.
//// /// [](){#option-show_docstring_classes} ## `show_docstring_classes` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Whether to render the "Classes" sections of docstrings. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_docstring_classes: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: show_docstring_classes: false ``` ```python """Summary. Classes: Class: Some class. """ class Class: """Summary.""" ``` /// admonition | Preview type: preview //// tab | With classesSummary.
Classes:
**Name** | **Description** -------- | --------------- `Class` | Some class.ClassSummary.
//// //// tab | Without classesSummary.
ClassSummary.
//// /// [](){#option-show_docstring_modules} ## `show_docstring_modules` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Whether to render the "Modules" sections of docstrings. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_docstring_modules: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: show_docstring_modules: false ``` ```tree module/ __init__.py submodule.py ``` ```python title="module/__init__.py" """Summary. Modules: submodule: Some module. """ ``` /// admonition | Preview type: preview //// tab | With modulesSummary.
Modules:
**Name** | **Description** ----------- | --------------- `submodule` | Some module. //// //// tab | Without modulesSummary.
//// /// [](){#option-show_docstring_description} ## `show_docstring_description` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Whether to render the textual blocks (including admonitions) of docstrings. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_docstring_description: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: show_docstring_description: false ``` ```python 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 blocksClassSummary.
Long description.
Stop using this class.
Attributes:
**Type** | **Name** | **Description** --------- | -------- | --------------- [`int`][] | `attr` | Some attribute. //// //// tab | Without description blocksClassAttributes:
**Type** | **Name** | **Description** --------- | -------- | --------------- [`int`][] | `attr` | Some attribute. //// /// [](){#option-show_docstring_examples} ## `show_docstring_examples` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Whether to render the "Examples" section of docstrings. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_docstring_examples: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: show_docstring_examples: false ``` ```python def print_hello(): """Print hello. Examples: >>> print("hello") hello """ print("hello") ``` /// admonition | Preview type: preview //// tab | With examplesprint_helloPrint hello.
Examples:
```pycon >>> print("hello") hello ``` //// //// tab | Without examplesprint_helloPrint hello.
//// /// [](){#option-show_docstring_other_parameters} ## `show_docstring_other_parameters` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Whether to render the "Other Parameters" section of docstrings. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_docstring_other_parameters: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: show_docstring_other_parameters: false ``` ```python def do_something(**kwargs): """Do something. Other parameters: whatever (int): Some integer. """ ``` /// admonition | Preview type: preview //// tab | With other parametersdo_somethingDo something.
Other parameters:
**Type** | **Name** | **Description** --------- | ---------- | --------------- [`int`][] | `whatever` | Some integer. //// //// tab | Without other parametersdo_somethingDo something.
//// /// [](){#option-show_docstring_parameters} ## `show_docstring_parameters` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Whether to render the "Parameters" section of docstrings. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_docstring_parameters: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: show_docstring_parameters: false ``` ```python def do_something(whatever: int = 0): """Do something. Parameters: whatever: Some integer. """ ``` /// admonition | Preview type: preview //// tab | With parametersdo_somethingDo something.
Parameters:
**Type** | **Name** | **Description** | **Default** --------- | ---------- | --------------- | ----------- [`int`][] | `whatever` | Some integer. | `0` //// //// tab | Without parametersdo_somethingDo something.
//// /// [](){#option-show_docstring_raises} ## `show_docstring_raises` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Whether to render the "Raises" section of docstrings. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_docstring_raises: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: show_docstring_raises: false ``` ```python def raise_runtime_error(): """Raise a runtime error. Raises: RuntimeError: Not good. """ raise RuntimeError ``` /// admonition | Preview type: preview //// tab | With exceptionsraise_runtime_errorRaise a runtime error.
Raises:
**Type** | **Description** ------------------ | --------------- [`RuntimeError`][] | Not good. //// //// tab | Without exceptionsraise_runtime_errorRaise a runtime error.
//// /// [](){#option-show_docstring_receives} ## `show_docstring_receives` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Whether to render the "Receives" section of docstrings. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_docstring_receives: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: show_docstring_receives: false ``` ```python 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 valuesiter_skipIterate and skip elements.
Receives:
**Type** | **Description** --------- | --------------- [`int`][] | Number of elements to skip. //// //// tab | Without received valuesiter_skipIterate and skip elements.
//// /// [](){#option-show_docstring_returns} ## `show_docstring_returns` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Whether to render the "Returns" section of docstrings. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_docstring_returns: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: show_docstring_returns: false ``` ```python def rand() -> int: """Return a random number. Returns: A random number. """ return random.randint(0, 1000) ``` /// admonition | Preview type: preview //// tab | With return valuerandReturn a random number.
Returns:
**Type** | **Description** --------- | --------------- [`int`][] | A random number. //// //// tab | Without return valuerandReturn a random number.
//// /// [](){#option-show_docstring_warns} ## `show_docstring_warns` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Whether to render the "Warns" section of docstrings. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_docstring_warns: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: show_docstring_warns: false ``` ```python def warn(): """Warn user. Warns: UserWarning: When this is inappropriate. """ warnings.warn(UserWarning("This is inappropriate")) ``` /// admonition | Preview type: preview //// tab | With warningswarnWarn user.
Warns:
**Type** | **Description** ----------------- | --------------- [`UserWarning`][] | When this is inappropriate. //// //// tab | Without warningswarnWarn user.
//// /// [](){#option-show_docstring_yields} ## `show_docstring_yields` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Whether to render the "Yields" section of docstrings. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_docstring_yields: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: show_docstring_yields: false ``` ```python 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 valuesiter_skipIterate and skip elements.
Yields:
**Type** | **Description** --------- | --------------- `T` | Elements of the iterable. //// //// tab | Without yielded valuesiter_skipIterate and skip elements.
//// ///