Members options¤

members¤

• Type list[str] | bool | None None

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

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          members:
          - hello  # (1)

1. Most of the time it won't make sense to use this option at the global level.

::: package.module
    options:
      members:
      - ThisClass
      - this_function

"""Module docstring."""


def this_function():
    """Function docstring."""


class ThisClass:
    """Class docstring."""

    def method(self):
        """Method docstring."""


this_attribute = 0
"""Attribute docstring."""

inherited_members¤

• Type list[str] | bool False

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

inherited_members: true
members:
- inherited_member_a
- inherited_member_b
- member_x
- member_y

The alternative is not supported:

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:

inherited_members: true
members: false

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

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 and docstrings.

inherited_members: true  # (1)
# members: null

1. In this case, both declared and inherited members will be subject to further filtering with filters and docstrings.

You can render all declared members and all or specific inherited members, avoiding further filtering with filters and docstrings by setting members: true:

inherited_members: true
members: true

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.

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

::: package.module
    options:
      inherited_members: true

"""Module docstring."""


class Base:
    """Base class."""

    def base(self):
        """Base method."""


class Main(Base):
    """Main class."""

    def main(self):
        """Main method."""

members_order¤

• Type str "alphabetical"

The members ordering to use. Possible values:

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

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          members_order: alphabetical

::: package.module
    options:
      members_order: source

"""Module docstring."""


def function_b():
    """Function a."""


def function_a():
    """Function b."""


def function_c():
    """Function c."""

filters¤

• Type list[str] | None ["!^_[^_]"]

A list of filters applied to filter objects based on their name.

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:

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

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          filters:
          - "!^_"

::: package.module
    options:
      filters: []

def hello():
    ...


def _world():
    ...

group_by_category¤

• Type bool True

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.

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

::: package.module
    options:
      group_by_category: false

def function_a():
    ...


class ClassB:
    ...


attribute_C = 0


def function_d():
    ...

show_submodules¤

• Type bool False

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.

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

::: package.subpackage
    options:
      show_submodules: false

📁 package
├──  __init__.py
└── 📁 subpackage
    ├──  __init__.py
    └──  submodule.py

summary¤

Insiders 1.2.0

• Type bool | dict[str, bool] False

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:

summary: true

summary: false

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.

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

::: path.to.module
    options:
      summary: false

::: path.to.module.MyClass
    options:
      summary: true

::: path.to.module.MyClass
    options:
      summary:
        functions: true

show_labels¤

• Type bool True

Whether to show labels of the members.

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

::: package.module
    options:
      show_labels: false

class SomeClass:
    some_attr: int