Headings options

heading

• Type str ""

A custom string to use as the heading of the root object (i.e. the object specified directly after the identifier :::). This will override the default heading generated by the plugin. See also the toc_label option.

Not advised to be used as a global configuration option.

This option is not advised to be used as a global configuration option, as it will override the default heading for all objects. It is recommended to use it only in specific cases where you want to override the heading for a specific object.

in docs/some_page.md (local configuration)

::: path.to.module
    options:
      heading: "My fancy module"

heading_level

• Type int 2

The initial heading level to use.

When injecting documentation for an object, the object itself and its members are rendered. For each layer of objects, we increase the heading level by 1.

The initial heading level will be used for the first layer. If you set it to 3, then headings will start with <h3>.

If the heading for the root object is not shown, then the initial heading level is used for its members.

in mkdocs.yml (global configuration)

plugins:
- mkdocstrings:
    handlers:
      python:
        options:
          heading_level: 2

or in docs/some_page.md (local configuration)

::: path.to.module
    options:
      heading_level: 3

Preview

With level 3 and root headingWith level 3, without root heading

module (3)

Docstring of the module.

ClassA (4)

Docstring of class A.

ClassB (4)

Docstring of class B.

method_1 (5)

Docstring of the method.

Docstring of the module.

ClassA (3)

Docstring of class A.

ClassB (3)

Docstring of class B.

method_1 (4)

Docstring of the method.

parameter_headings

Insiders 1.6.0

• Type bool False

Whether to render headings for function/method parameters.

With this option enabled, each function/method parameter (including parameters of __init__ methods merged in their parent class with the merge_init_into_class option) gets a permalink, an entry in the Table of Contents, and an entry in the generated objects inventory. The permalink and inventory entry allow cross-references from internal and external pages.

The identifier used in the permalink and inventory is of the following form: path.to.function(param_name). To manually cross-reference a parameter, you can therefore use this Markdown syntax:

- Class parameter: [`param`][package.module.Class(param)]
- Method parameter: [`param`][package.module.Class.method(param)]
- Function parameter: [`param`][package.module.function(param)]
- Variadic positional parameters: [`*args`][package.module.function(*args)]
- Variadic keyword parameters: [`**kwargs`][package.module.function(**kwargs)]

Enabling this option along with signature_crossrefs will automatically render cross-references to parameters in class/function/method signatures and attributes values.

in mkdocs.yml (global configuration)

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

or in docs/some_page.md (local configuration)

::: path.to.module
    options:
      parameter_headings: true

Preview: Cross-references

get_version

get_version(dist: str = 'mkdocstrings-python') -> str

Get version of the given distribution.

Parameters:

• dist

  (str, default: 'mkdocstrings-python' ) –

  A distribution name.

Returns:

• str –

  A version number.

current_version module-attribute

current_version: str = get_version(dist='mkdocstrings-python')

Current package version.

Preview: Parameter sections

Table styleList styleSpacy style

Parameters:

Name	Type	Description	Default
dist	str	A distribution name.	'mkdocstrings-python'

Parameters:

• dist

  (str, default: 'mkdocstrings-python' ) –

  A distribution name.

PARAMETER	DESCRIPTION
dist	A distribution name. TYPE: str DEFAULT: 'mkdocstrings-python'

Preview: Table of contents (with symbol types)

get_version
dist

To customize symbols, see Customizing symbol types.

show_root_heading

• Type bool False

Show the heading of the object at the root of the documentation tree (i.e. the object referenced by the identifier after :::).

It is pretty common to inject documentation for one module per page, especially when following our automatic reference pages recipe. Since each page already has a title, usually being the module's name, we can spare one heading level by not showing the heading for the module itself (heading levels are limited to 6 by the HTML specification).

Sparing that extra level can be helpful when your objects tree is deeply nested (e.g. method in a class in a class in a module). If your objects tree is not deeply nested, and you are injecting documentation for many different objects on a single page, it might be preferable to render the heading of each object.

in mkdocs.yml (global configuration)

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

or in docs/some_page.md (local configuration)

::: path.to.ClassA
    options:
      show_root_heading: true

::: path.to.ClassB
    options:
      show_root_heading: true

Preview

With root headingWithout root heading

ClassA (2)

Docstring of class A.

method_a1 (3)

Docstring of the method.

ClassB (2)

Docstring of class B.

method_b1 (3)

Docstring of the method.

Docstring of class A.

method_a1 (2)

Docstring of the method.

Docstring of class B.

method_b1 (2)

Docstring of the method.

show_root_toc_entry

• Type bool True

If the root heading is not shown, at least add a ToC entry for it.

If you inject documentation for an object in the middle of a page, after long paragraphs, and without showing the root heading, then you will not be able to link to this particular object as it won't have a permalink and will be "lost" in the middle of text. In that case, it is useful to add a hidden anchor to the document, which will also appear in the table of contents.

In other cases, you might want to disable the entry to avoid polluting the ToC. It is not possible to show the root heading and hide the ToC entry.

in mkdocs.yml (global configuration)

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

or in docs/some_page.md (local configuration)

## Some heading

Lots of text.

::: path.to.object
    options:
      show_root_toc_entry: false

## Other heading.

More text.

Preview

With ToC entryWithout ToC entry

Table of contents Some heading object Other heading

Table of contents Some heading Other heading

show_root_full_path

• Type bool True

Show the full Python path for the root object heading.

The path of a Python object is the dot-separated list of names under which it is accessible, for example package.module.Class.method.

With this option you can choose to show the full path of the object you inject documentation for, or just its name. This option impacts only the object you specify, not its members. For members, see the two other options show_root_members_full_path and show_object_full_path.

in mkdocs.yml (global configuration)

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

or in docs/some_page.md (local configuration)

::: package.module.Class.method
    options:
      show_root_full_path: false

Preview

With root full pathWithout root full path

package.module.Class.method

Docstring of the method.

method

Docstring of the method.

show_root_members_full_path

• Type bool False

Show the full Python path of the root members.

This option does the same thing as show_root_full_path, but for direct members of the root object instead of the root object itself.

To show the full path for every member recursively, see show_object_full_path.

in mkdocs.yml (global configuration)

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

or in docs/some_page.md (local configuration)

::: package.module
    options:
      show_root_members_full_path: false

Preview

With members full pathWithout members full path

Docstring of the module.

package.module.Class

Docstring of the class.

method

Docstring of the method.

Docstring of the module.

Class

Docstring of the class.

method

Docstring of the method.

show_object_full_path

• Type bool False

Show the full Python path of every object.

Same as for show_root_members_full_path, but for every member, recursively. This option takes precedence over show_root_members_full_path:

show_root_members_full_path	show_object_full_path	Direct root members path
False	False	Name only
False	True	Full
True	False	Full
True	True	Full

in mkdocs.yml (global configuration)

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

or in docs/some_page.md (local configuration)

::: package.module
    options:
      show_object_full_path: false

Preview

With objects full pathWithout objects full path

Docstring of the module.

package.module.Class

Docstring of the class.

package.module.Class.method

Docstring of the method.

Docstring of the module.

Class

Docstring of the class.

method

Docstring of the method.

show_category_heading

• Type bool False

When grouped by categories, show a heading for each category. These category headings will appear in the table of contents, allowing you to link to them using their permalinks.

Not recommended with deeply nested objects.

When injecting documentation for deeply nested objects, you'll quickly run out of heading levels, and the objects at the bottom of the tree risk all getting documented using H6 headings, which might decrease the readability of your API docs.

in mkdocs.yml (global configuration)

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

or in docs/some_page.md (local configuration)

::: package.module
    options:
      group_by_category: true
      show_category_heading: false

Preview

With category headingsWithout category headings

Docstring of the module.

Attributes (2)

module_attribute (3)

Docstring of the module attribute.

Classes (2)

Class (3)

Docstring of the class.

Attributes (4)

class_attribute (5)

Docstring of the class attribute.

Methods (4)

method (5)

Docstring of the method.

Docstring of the module.

module_attribute (2)

Docstring of the module attribute.

Class (2)

Docstring of the class.

class_attribute (3)

Docstring of the class attribute.

method (3)

Docstring of the method.

show_symbol_type_heading

Insiders 1.1.0

• Type bool False

Show the symbol type in headings.

This option will prefix headings with , , , or types. See also show_symbol_type_toc.

To customize symbols, see Customizing symbol types.

in mkdocs.yml (global configuration)

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

or in docs/some_page.md (local configuration)

::: package.module
    options:
      show_symbol_type_heading: false

Preview

With symbol type in headingsWithout symbol type in headings

module

Docstring of the module.

attribute

Docstring of the module attribute.

function

Docstring of the function.

Class

Docstring of the class.

method

Docstring of the method.

module

Docstring of the module.

attribute

Docstring of the module attribute.

function

Docstring of the function.

Class

Docstring of the class.

method

Docstring of the method.

show_symbol_type_toc

Insiders 1.1.0

• Type bool False

Show the symbol type in the Table of Contents.

This option will prefix items in the ToC with , , , or types. See also show_symbol_type_heading.

To customize symbols, see Customizing symbol types.

in mkdocs.yml (global configuration)

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

or in docs/some_page.md (local configuration)

::: package.module
    options:
      show_symbol_type_toc: false

Preview

With symbol type in ToCWithout symbol type in ToC

• module
• attribute
• function
• Class
  • method

• module
• attribute
• function
• Class
  • method

toc_label

• Type str ""

A custom string to use as the label in the Table of Contents for the root object (i.e. the one specified directly after the identifier :::). This will override the default label generated by the plugin. See also the heading option.

Not advised to be used as a global configuration option.

This option is not advised to be used as a global configuration option, as it will override the default label for all objects. It is recommended to use it only in specific cases where you want to override the label for a specific object.

Use with/without heading.

If you use this option without specifying a custom heading, the default heading will be used in the page, but the label in the Table of Contents will be the one you specified. By providing both an option for heading and toc_label, we leave the customization entirely up to you.

in docs/some_page.md (local configuration)

::: path.to.module
    options:
      heading: "My fancy module"
      toc_label: "My fancy module"

Feedback