list [ str ] | bool | None :material-equal: `None`{ title="default value" }** An explicit list of members to render. Only members declared in this list will be rendered. A member without a docstring will still be rendered, even if [`show_if_no_docstring`][] is set to false. The members will be rendered in the specified order, regardless of the value of [`members_order`][]. **Note that members will still be grouped by category, according to the [`group_by_category`][] option.** Passing a falsy value (`no`, `false` in YAML) or an empty list (`[]`) will tell the Python handler not to render any member. Passing a truthy value (`yes`, `true` in YAML) will tell the Python handler to render every member. Any given value, except for an explicit `None` (`null` in YAML) will tell the handler to ignore [`filters`][] for the object's members. Filters will still be applied to the next layers of members (grand-children). ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: members: - hello # (1) ``` 1. :warning: Most of the time it won't make sense to use this option at the global level. ```md title="or in docs/some_page.md (local configuration)" ::: package.module options: members: - ThisClass - this_function ``` ```python title="package/module.py" """Module docstring.""" def this_function(): """Function docstring.""" class ThisClass: """Class docstring.""" def method(self): """Method docstring.""" this_attribute = 0 """Attribute docstring.""" ``` /// admonition | Preview type: preview //// tab | With `members: true`
Module docstring.
this_function
Function docstring.
ThisClass
Class docstring.
method
Method docstring.
this_attribute
Attribute docstring.
//// //// tab | With `members: false` or `members: []`Module docstring.
//// //// tab | With `members: [ThisClass]`Module docstring.
ThisClass
Class docstring.
method
Method docstring.
//// /// INFO: **The default behavior (with unspecified `members` or `members: null`) is to use [`filters`][].** [](){#option-inherited_members} ## `inherited_members` - **:octicons-package-24: Type list [ str ] | bool :material-equal: `False`{ title="default value" }** An explicit list of inherited members (for classes) to render. Inherited members are always fetched from classes that are in the same package as the currently rendered class. To fetch members inherited from base classes, themselves coming from external packages, use the [`preload_modules`][preload_modules] option. For example, if your class inherits from Pydantic's `BaseModel`, and you want to render `BaseModel`'s methods in your class, use `preload_modules: [pydantic]`. The `pydantic` package must be available in the current environment. Passing a falsy value (`no`, `false` in YAML) or an empty list (`[]`) will tell the Python handler not to render any inherited member. Passing a truthy value (`yes`, `true` in YAML) will tell the Python handler to render every inherited member. When all inherited members are selected with `inherited_members: true`, it is possible to specify both members and inherited members in the `members` list: ```yaml inherited_members: true members: - inherited_member_a - inherited_member_b - member_x - member_y ``` The alternative is not supported: ```yaml inherited_members: - inherited_member_a - inherited_member_b members: - member_x - member_y ``` ...because it would make members ordering ambiguous/unspecified. You can render inherited members *only* by setting `inherited_members: true` (or a list of inherited members) and setting `members: false`: ```yaml inherited_members: true members: false ``` ```yaml inherited_members: - inherited_member_a - inherited_member_b members: false ``` You can render *all declared members* and all or specific inherited members by leaving `members` as null (default): ```yaml inherited_members: - inherited_member_a - inherited_member_b # members: null # (1) ``` 1. In this case, only declared members will be subject to further filtering with [`filters`][filters] and [`docstrings`][show_if_no_docstring]. ```yaml inherited_members: true # (1) # members: null ``` 1. In this case, both declared and inherited members will be subject to further filtering with [`filters`][filters] and [`docstrings`][show_if_no_docstring]. You can render *all declared members* and all or specific inherited members, avoiding further filtering with [`filters`][filters] and [`docstrings`][show_if_no_docstring] by setting `members: true`: ```yaml inherited_members: true members: true ``` ```yaml inherited_members: - inherited_member_a - inherited_member_b members: true ``` The general rule is that declared or inherited members specified in lists are never filtered out. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: inherited_members: false ``` ```md title="or in docs/some_page.md (local configuration)" ::: package.module options: inherited_members: true ``` ```python title="package/module.py" """Module docstring.""" class Base: """Base class.""" def base(self): """Base method.""" class Main(Base): """Main class.""" def main(self): """Main method.""" ``` /// admonition | Preview type: preview //// tab | With inherited members
Module docstring.
Base
Base class.
base
Base method.
Main
Main class.
base
Base method.
main
Main method.
//// //// tab | Without inherited membersModule docstring.
Base
Base class.
base
Base method.
Main
Main class.
main
Main method.
//// /// [](){#option-members_order} ## `members_order` - **:octicons-package-24: Type `str | list[str]` :material-equal: `"alphabetical"`{ title="default value" }** The members ordering to use. Possible values: - `__all__` ([:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } — [:octicons-tag-24: Insiders 1.12.0](../../insiders/changelog.md#1.12.0)): Order according to `__all__` attributes. Since classes do not define `__all__` attributes, you can specify a second ordering method by using a list. - `alphabetical`: Order by the members names. - `source`: Order members as they appear in the source file. The order applies for all members, recursively. The order will be ignored for members that are explicitely sorted using the [`members`][] option. **Note that members will still be grouped by category, according to the [`group_by_category`][] option.** ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: members_order: alphabetical ``` ```md title="or in docs/some_page.md (local configuration)" ::: package.module options: members_order: source ``` ```md title="or in docs/some_page.md (local configuration)" ::: package.module options: members_order: [__all__, source] ``` ```python title="package/module.py" """Module docstring.""" def function_b(): """Function a.""" def function_a(): """Function b.""" def function_c(): """Function c.""" ``` /// admonition | Preview type: preview //// tab | With alphabetical orderModule docstring.
function_a
Function a.
function_b
Function b.
function_c
Function c.
//// //// tab | With source orderModule docstring.
function_b
Function b.
function_a
Function a.
function_c
Function c.
//// /// [](){#option-filters} ## `filters` - **:octicons-package-24: Type list [ str ] | Literal ["public"] | None :material-equal: `["!^_[^_]"]`{ title="default value" }** A list of filters, or `"public"`. **Filtering methods** [](){#option-filters-public} [:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } — [:octicons-tag-24: Insiders 1.11.0](../../insiders/changelog.md#1.11.0) The `public` filtering method will include only public objects: those added to the `__all__` attribute of modules, or not starting with a single underscore. Special methods and attributes ("dunder" methods/attributes, starting and ending with two underscores), like `__init__`, `__call__`, `__mult__`, etc., are always considered public. **List of filters** Filters are regular expressions. These regular expressions are evaluated by Python and so must match the syntax supported by the [`re`][] module. A filter starting with `!` (negative filter) will exclude matching objects instead of including them. The default value (`["!^_[^_]"]`) means: *render every object, except those starting with one underscore, unless they start with two underscores*. It means that an object whose name is `hello`, `__hello`, or `__hello__` will be rendered, but not one whose name is `_hello`. Each filter takes precedence over the previous one. This allows for fine-grain selection of objects by adding more specific filters. For example, you can start by unselecting objects that start with `_`, and add a second filter that re-select objects that start with `__`. The default filters can therefore be rewritten like this: ```yaml filters: - "!^_" - "^__" ``` If there are no negative filters, the handler considers that everything is **unselected** first, and then selects things based on your positive filters. If there is at least one negative filter, the handler considers that everything is **selected** first, and then re-selects/unselects things based on your other filters. In short, `filters: ["a"]` means *"keep ***nothing*** except names containing `a`"*, while `filters: ["!a"]` means *"keep ***everything*** except names containing `a`"*. An empty list of filters tells the Python handler to render every object. The [`members`][] option takes precedence over filters (filters will still be applied recursively to lower members in the hierarchy). ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: filters: - "!^_[^_]" ``` ```md title="or in docs/some_page.md (local configuration)" ::: package.module options: filters: public ``` ```python title="package/module.py" def hello(): ... def _world(): ... ``` /// admonition | Preview type: preview //// tab | With `filters: []`
Module docstring.
hello
Function docstring.
_world
Function docstring.
//// //// tab | With `filters: ["hello"]`Module docstring.
hello
Function docstring.
//// //// tab | With `filters: ["!hello"]`Module docstring.
_world
Function docstring.
//// /// /// admonition | Common filters type: tip Here are some common filters that you might to want to use. - `["!^_"]`: exclude all private/protected/special objects - `["!^_", "^__init__$"]`: same as above, but keep `__init__` methods - `["!^_[^_]"]`: exclude all private/protected objects, keep special ones (default filters) /// [](){#option-group_by_category} ## `group_by_category` - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** Group the object members by categories: attributes, classes, functions, and modules. Members within a same category will be ordered according to the [`members_order`][] option. You can use the [`show_category_heading`][] option to also render a heading for each category. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: group_by_category: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: package.module options: group_by_category: false ``` ```python title="package/module.py" def function_a(): ... class ClassB: ... attribute_C = 0 def function_d(): ... ``` /// admonition | Preview type: preview //// tab | With category groupingModule docstring.
attribute_c
Attribute docstring.
ClassB
Class docstring.
function_a
Function docstring.
function_d
Function docstring.
//// //// tab | Without category groupingModule docstring.
function_a
Function docstring.
ClassB
Class docstring.
attribute_c
Attribute docstring.
function_d
Function docstring.
//// /// [](){#option-show_submodules} ## `show_submodules` - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** When rendering a module, show its submodules recursively. This is false by default, because most of the time we render only one module per page, and when rendering a package (a tree of modules and their members) on a single page, we quickly run out of [heading levels][heading_level]. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: show_submodules: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: package.subpackage options: show_submodules: false ``` ```tree title="package" package __init__.py subpackage __init__.py submodule.py ``` /// admonition | Preview type: preview //// tab | With submodulesSubpackage docstring.
subpackage_member
Member docstring.
submodule
Submodule docstring.
submodule_member
Member docstring.
//// //// tab | Without submodulesSubpackage docstring.
subpackage_member
Member docstring.
//// /// [](){#option-summary} ## `summary` [:octicons-tag-24: Insiders 1.2.0](../../insiders/changelog.md#1.2.0) - **:octicons-package-24: Type bool | dict [ str , bool ] :material-equal: `False`{ title="default value" }** Whether to render summaries of modules, classes, functions (methods) and attributes. This option accepts a boolean (`yes`, `true`, `no`, `false` in YAML) or a dictionary with one or more of the following keys: `attributes`, `functions`, `classes`, `modules`, with booleans as values. Class methods summary is (de)activated with the `functions` key. By default, `summary` is false, and by extension all values are false. Examples: ```yaml summary: true ``` ```yaml summary: false ``` ```yaml summary: attributes: false functions: true modules: false ``` Summaries will be rendered as the corresponding docstring sections. For example, the summary for attributes will be rendered as an Attributes docstring section. The section will be rendered in accordance with the [`docstring_section_style`][] option. If the objects appearing in the summary are also rendered on the page (or somewhere else on the site), their name will automatically link to their rendered documentation. ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: handlers: python: options: summary: true ``` ```md title="or in docs/some_page.md (local configuration)" ::: path.to.module options: summary: false ``` /// admonition | Preview type: preview //// tab | With all summaries ``` ::: path.to.module.MyClass options: summary: true ``` MyClass
Class docstring.
Methods:
Attributes:
Class docstring.
Methods:
some_attr: int instance-attribute //// //// tab | Without labels some_attr: int //// ///
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4