Skip to content

members.md

Latest commit

 

History

History
716 lines (563 loc) · 18.9 KB

members.md

File metadata and controls

716 lines (563 loc) · 18.9 KB

Members options

{#option-members}

members

  • :octicons-package-24: Type 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).

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

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

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][filters] and [docstrings][show_if_no_docstring].
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:

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

/// 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 members

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

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
::: package.module
    options:
      members_order: [__all__, source]
"""Module docstring."""


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


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


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

/// admonition | Preview type: preview

//// tab | With alphabetical order

Module docstring.

function_a

Function a.

function_b

Function b.

function_c

Function c.

////

//// tab | With source order

Module 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 } — :octicons-tag-24: Insiders 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:

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

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

/// admonition | Preview type: preview

//// tab | With category grouping

Module docstring.

attribute_c

Attribute docstring.

ClassB

Class docstring.

function_a

Function docstring.

function_d

Function docstring.

////

//// tab | Without category grouping

Module 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].

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          show_submodules: true
::: package.subpackage
    options:
      show_submodules: false
package
    __init__.py
    subpackage
        __init__.py
        submodule.py

/// admonition | Preview type: preview

//// tab | With submodules

Subpackage docstring.

subpackage_member

Member docstring.

submodule

Submodule docstring.

submodule_member

Member docstring.

////

//// tab | Without submodules

Subpackage docstring.

subpackage_member

Member docstring.

//// ///

{#option-summary}

summary

:octicons-tag-24: Insiders 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:

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

/// admonition | Preview type: preview

//// tab | With all summaries

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

MyClass

Class docstring.

Methods:

  • my_method1: Summary of the method (first docstring line).
  • my_method2: Summary of the method (first docstring line).

Attributes:

  • attr1: Summary of the attribute (first docstring line).
  • attr2: Summary of the attribute (first docstring line).
////

//// tab | With methods summary only

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

MyClass

Class docstring.

Methods:

  • my_method1: Summary of the method (first docstring line).
  • my_method2: Summary of the method (first docstring line).
//// ///

{#option-show_labels}

show_labels

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

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

/// admonition | Preview type: preview

//// tab | With labels some_attr: int instance-attribute ////

//// tab | Without labels some_attr: int //// ///