Headings options

{#option-heading}

`heading`

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

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][option-toc_label].

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

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

{#option-heading_level}

`heading_level`

:octicons-package-24: Type [int][] :material-equal: 2{ title="default value" }

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][show_root_heading] is not shown, then the initial heading level is used for its members.

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

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

/// admonition | Preview type: preview

//// tab | With level 3 and 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.

////

//// tab | With level 3, without root heading

Docstring of the module.

`ClassA` (3)

Docstring of class A.

`ClassB` (3)

Docstring of class B.

`method_1` (4)

Docstring of the method.

//// ///

{#option-parameter_headings}

`parameter_headings`

:octicons-tag-24: Insiders 1.6.0

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

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.

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

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

/// admonition | Preview: Cross-references type: preview

::: package.get_version
    options:
      heading_level: 3
      parameter_headings: true
      docstring_section_style: list

::: package.current_version
    options:
      heading_level: 3
      line_length: 100

///

/// admonition | Preview: Parameter sections type: preview

//// tab | Table style

::: package.get_version
    options:
      heading_level: 3
      show_root_heading: false
      show_root_toc_entry: false
      parameter_headings: true
      docstring_section_style: table
      show_docstring_returns: false
      show_docstring_description: false

////

//// tab | List style

::: package.get_version
    options:
      heading_level: 3
      show_root_heading: false
      show_root_toc_entry: false
      parameter_headings: true
      docstring_section_style: list
      show_docstring_returns: false
      show_docstring_description: false

////

//// tab | Spacy style

::: package.get_version
    options:
      heading_level: 3
      show_root_heading: false
      show_root_toc_entry: false
      parameter_headings: true
      docstring_section_style: spacy
      show_docstring_returns: false
      show_docstring_description: false

//// ///

/// admonition | Preview: Table of contents (with symbol types) type: preview

get_version
dist

To customize symbols, see Customizing symbol types.

///

{#option-show_root_heading}

`show_root_heading`

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

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][autopages 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.

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

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

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

/// admonition | Preview type: preview

//// tab | With 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.

////

//// tab | Without root heading

Docstring of class A.

`method_a1` (2)

Docstring of the method.

Docstring of class B.

`method_b1` (2)

Docstring of the method.

//// ///

{#option-show_root_toc_entry}

`show_root_toc_entry`

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

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][show_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.

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

## Some heading

Lots of text.

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

## Other heading.

More text.

/// admonition | Preview type: preview

//// tab | With ToC entry Table of contents Some heading{ title="#permalink-to-some-heading" } object{ title="#permalink-to-object" } Other heading{ title="#permalink-to-other-heading" } ////

//// tab | Without ToC entry Table of contents Some heading{ title="#permalink-to-some-heading" } Other heading{ title="#permalink-to-other-heading" } //// ///

{#option-show_root_full_path}

`show_root_full_path`

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

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

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

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

/// admonition | Preview type: preview

//// tab | With root full path

`package.module.Class.method`

Docstring of the method.

////

//// tab | Without root full path

`method`

Docstring of the method.

//// ///

{#option-show_root_members_full_path}

`show_root_members_full_path`

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

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

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

::: package.module
    options:
      show_root_members_full_path: false

/// admonition | Preview type: preview

//// tab | With members full path

Docstring of the module.

`package.module.Class`

Docstring of the class.

`method`

Docstring of the method.

////

//// tab | Without members full path

Docstring of the module.

`Class`

Docstring of the class.

`method`

Docstring of the method.

//// ///

{#option-show_object_full_path}

`show_object_full_path`

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

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

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

::: package.module
    options:
      show_object_full_path: false

/// admonition | Preview type: preview

//// tab | With objects full path

Docstring of the module.

`package.module.Class`

Docstring of the class.

`package.module.Class.method`

Docstring of the method.

////

//// tab | Without objects full path

Docstring of the module.

`Class`

Docstring of the class.

`method`

Docstring of the method.

//// ///

{#option-show_category_heading}

`show_category_heading`

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

When [grouped by categories][group_by_category], 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.

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

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

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

/// admonition | Preview type: preview

//// tab | With 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.

////

//// tab | Without category headings

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.

//// ///

{#option-show_symbol_type_heading}

`show_symbol_type_heading`

:octicons-tag-24: Insiders 1.1.0

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

Show the symbol type in headings.

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

To customize symbols, see Customizing symbol types.

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

::: package.module
    options:
      show_symbol_type_heading: false

/// admonition | Preview type: preview

//// tab | With 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.

////

//// tab | Without 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.

//// ///

{#option-show_symbol_type_toc}

`show_symbol_type_toc`

:octicons-tag-24: Insiders 1.1.0

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

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][show_symbol_type_heading].

To customize symbols, see Customizing symbol types.

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

::: package.module
    options:
      show_symbol_type_toc: false

/// admonition | Preview type: preview

//// tab | With symbol type in ToC

module
attribute
function
Class
- method

////

//// tab | Without symbol type in ToC

module
attribute
function
Class
- method

//// ///

{#option-toc_label}

`toc_label`

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

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][option-heading].

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

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

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

Uh oh!

FilesExpand file tree

headings.md

Latest commit

History

headings.md

File metadata and controls

Headings options

heading

heading_level

module (3)

ClassA (4)

ClassB (4)

method_1 (5)

ClassA (3)

ClassB (3)

method_1 (4)

parameter_headings

show_root_heading

ClassA (2)

method_a1 (3)

ClassB (2)

method_b1 (3)

method_a1 (2)

method_b1 (2)

show_root_toc_entry

show_root_full_path

package.module.Class.method

method

show_root_members_full_path

package.module.Class

method

Class

method

show_object_full_path

package.module.Class

package.module.Class.method

Class

method

show_category_heading

Attributes (2)

module_attribute (3)

Classes (2)

Class (3)

Attributes (4)

class_attribute (5)

Methods (4)

method (5)

module_attribute (2)

Class (2)

class_attribute (3)

method (3)

show_symbol_type_heading

module

attribute

function

Class

method

module

attribute

function

Class

method

show_symbol_type_toc

toc_label

`heading`

`heading_level`

`module` (3)

`ClassA` (4)

`ClassB` (4)

`method_1` (5)

`ClassA` (3)

`ClassB` (3)

`method_1` (4)

`parameter_headings`

`show_root_heading`

`ClassA` (2)

`method_a1` (3)

`ClassB` (2)

`method_b1` (3)

`method_a1` (2)

`method_b1` (2)

`show_root_toc_entry`

`show_root_full_path`

`package.module.Class.method`

`method`

`show_root_members_full_path`

`package.module.Class`

`method`

`Class`

`method`

`show_object_full_path`

`package.module.Class`

`package.module.Class.method`

`Class`

`method`

`show_category_heading`

`module_attribute` (3)

`Class` (3)

`class_attribute` (5)

`method` (5)

`module_attribute` (2)

`Class` (2)

`class_attribute` (3)

`method` (3)

`show_symbol_type_heading`

`module`

`attribute`

`function`

`Class`

`method`

`module`

`attribute`

`function`

`Class`

`method`

`show_symbol_type_toc`

`toc_label`