Headings options¤

`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:
      matlab:
        options:
          heading_level: 2

or in docs/some_page.md (local configuration)

::: matlab_callable
    options:
      heading_level: 3

Source files

tree readme.md classA.m classB.m typed_function.m

📁 +mynamespace
├── 📄 readme.md
├── 📄 classA.m
├── 📄 classB.m
└── 📄 typed_function.m

This is the docstring for mynamespace.

classdef classA
    % Docstring of class A.

    methods
        function obj = method_a(inputArg1)
            % Docstring of the method.
        end
    end
end

classdef classB
    % Docstring of class B.
    properties
        prop_b   % Docstring of the property.
    end
    methods
        function obj = method_b(inputArg1)
            % Docstring of the method.
        end
    end
end

function output = typed_function(input, options)
    % Example function with typed inputs and outputs
    arguments (Input)
        input (1,1) string % The input variable
        options.keyword (1,1) double = 0 % An optional keyword argument
    end
    arguments (Output)
        output (1,:) char % The output variable
    end
    output = char(input);
end

Preview

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

`mynamespace` (3)

Docstring of the package namespace.

`ClassA` (4)

Docstring of class A.

`ClassB` (4)

Docstring of class B.

`myfunction` (5)

Docstring of the function.

Docstring of the package namespace.

`ClassA` (3)

Docstring of class A.

`ClassB` (3)

Docstring of class B.

`myfunction` (4)

Docstring of the function.

`parameter_headings`¤

Type bool False

Whether to render headings for function/method parameters.

With this option enabled, each function/method parameter (including parameters of the constructor methods merged in their parent class with the merge_constructor_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 arameter, 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)]

in mkdocs.yml (global configuration)

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

or in docs/some_page.md (local configuration)

::: matlab_callable
    options:
      parameter_headings: true

Source files

tree readme.md classA.m classB.m typed_function.m

📁 +mynamespace
├── 📄 readme.md
├── 📄 classA.m
├── 📄 classB.m
└── 📄 typed_function.m

This is the docstring for mynamespace.

classdef classA
    % Docstring of class A.

    methods
        function obj = method_a(inputArg1)
            % Docstring of the method.
        end
    end
end

classdef classB
    % Docstring of class B.
    properties
        prop_b   % Docstring of the property.
    end
    methods
        function obj = method_b(inputArg1)
            % Docstring of the method.
        end
    end
end

function output = typed_function(input, options)
    % Example function with typed inputs and outputs
    arguments (Input)
        input (1,1) string % The input variable
        options.keyword (1,1) double = 0 % An optional keyword argument
    end
    arguments (Output)
        output (1,:) char % The output variable
    end
    output = char(input);
end

Preview: Cross-references

With parameter headingsWithout parameter headings

::: mynamespace.typed_function
    options:
      parameter_headings: true

`mynamespace.typed_function(input, /, *, keyword=0)` ¤

Example function with typed inputs and outputs

Parameters:

input ¤
(string) –

The input variable

Name-Value Arguments:

keyword (double) –

An optional keyword argument

Returns:

output ( char ) –

The output variable

::: mynamespace.typed_function
    options:
      parameter_headings: false

`mynamespace.typed_function(input, /, *, keyword=0)` ¤

Example function with typed inputs and outputs

Parameters:

input (string) –

The input variable

Name-Value Arguments:

keyword (double) –

An optional keyword argument

Returns:

output ( char ) –

The output variable

Preview: Parameter sections

Table styleList styleSpacy style

Parameters:

Name	Type	Description	Default
`input` ¤	`string`	The input variable	required

Name-Value Arguments:

Name	Type	Description
`keyword`	`double`	An optional keyword argument

Parameters:

input ¤
(string) –

The input variable

Name-Value Arguments:

keyword (double) –

An optional keyword argument

PARAMETER	DESCRIPTION
`input` ¤	The input variable TYPE: `string`

NAME-VALUE ARGUMENTS	DESCRIPTION
`keyword`	An optional keyword argument TYPE: `double`

Preview: Table of contents (with symbol types)

typed_function
input

`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. 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:
      matlab:
        options:
          show_root_heading: false

or in docs/some_page.md (local configuration)

::: mynamespace.ClassA
    options:
      show_root_heading: true

::: mynamespace.ClassB
    options:
      show_root_heading: true

Source files

tree readme.md classA.m classB.m typed_function.m

📁 +mynamespace
├── 📄 readme.md
├── 📄 classA.m
├── 📄 classB.m
└── 📄 typed_function.m

This is the docstring for mynamespace.

classdef classA
    % Docstring of class A.

    methods
        function obj = method_a(inputArg1)
            % Docstring of the method.
        end
    end
end

classdef classB
    % Docstring of class B.
    properties
        prop_b   % Docstring of the property.
    end
    methods
        function obj = method_b(inputArg1)
            % Docstring of the method.
        end
    end
end

function output = typed_function(input, options)
    % Example function with typed inputs and outputs
    arguments (Input)
        input (1,1) string % The input variable
        options.keyword (1,1) double = 0 % An optional keyword argument
    end
    arguments (Output)
        output (1,:) char % The output variable
    end
    output = char(input);
end

Preview

With root headingWithout root heading

`mynamespace.classA` ¤

Docstring of class A.

`method_a()` ¤

Docstring of the method.

`mynamespace.classB` ¤

Docstring of class B.

`prop_b` ¤

Docstring of the property.

`method_b()` ¤

Docstring of the method.

Docstring of class A.

`method_a()` ¤

Docstring of the method.

Docstring of class B.

`prop_b` ¤

Docstring of the property.

`method_b()` ¤

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:
      matlab:
        options:
          show_root_toc_entry: true

or in docs/some_page.md (local configuration)

## Some heading

Lots of text.

::: matlab_callable
    options:
      show_root_toc_entry: false

## Other heading.

More text.

Preview

With ToC entryWithout ToC entry

::: matlab_callable
    options:
      show_root_toc_entry: true

Table of contents
Some heading
matlab_callable
Other heading

::: matlab_callable
    options:
      show_root_toc_entry: false

Table of contents
Some heading
Other heading

`show_root_full_path`¤

Type bool True

Show the full namespace path for the root object heading.

The namespace path of a MATLAB object is the dot-separated list of names under which it is accessible, for example namespace.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:
      matlab:
        options:
          show_root_full_path: true

or in docs/some_page.md (local configuration)

::: mynamespace.classA
    options:
      show_root_full_path: false

Source files

tree readme.md classA.m classB.m typed_function.m

📁 +mynamespace
├── 📄 readme.md
├── 📄 classA.m
├── 📄 classB.m
└── 📄 typed_function.m

This is the docstring for mynamespace.

classdef classA
    % Docstring of class A.

    methods
        function obj = method_a(inputArg1)
            % Docstring of the method.
        end
    end
end

classdef classB
    % Docstring of class B.
    properties
        prop_b   % Docstring of the property.
    end
    methods
        function obj = method_b(inputArg1)
            % Docstring of the method.
        end
    end
end

function output = typed_function(input, options)
    % Example function with typed inputs and outputs
    arguments (Input)
        input (1,1) string % The input variable
        options.keyword (1,1) double = 0 % An optional keyword argument
    end
    arguments (Output)
        output (1,:) char % The output variable
    end
    output = char(input);
end

Preview

With root full pathWithout root full path

::: mynamespace.classA
    options:
      show_root_full_path: true

`mynamespace.classA` ¤

Docstring of class A.

`method_a()` ¤

Docstring of the method.

::: mynamespace.classA
    options:
      show_root_full_path: false

`classA` ¤

Docstring of class A.

`method_a()` ¤

Docstring of the method.

`show_root_members_full_path`¤

Type bool False

Show the full namespace 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:
      matlab:
        options:
          show_root_members_full_path: true

or in docs/some_page.md (local configuration)

::: mynamespace.classA
    options:
      show_root_members_full_path: false

Source files

tree readme.md classA.m classB.m typed_function.m

📁 +mynamespace
├── 📄 readme.md
├── 📄 classA.m
├── 📄 classB.m
└── 📄 typed_function.m

This is the docstring for mynamespace.

classdef classA
    % Docstring of class A.

    methods
        function obj = method_a(inputArg1)
            % Docstring of the method.
        end
    end
end

classdef classB
    % Docstring of class B.
    properties
        prop_b   % Docstring of the property.
    end
    methods
        function obj = method_b(inputArg1)
            % Docstring of the method.
        end
    end
end

function output = typed_function(input, options)
    % Example function with typed inputs and outputs
    arguments (Input)
        input (1,1) string % The input variable
        options.keyword (1,1) double = 0 % An optional keyword argument
    end
    arguments (Output)
        output (1,:) char % The output variable
    end
    output = char(input);
end

Preview

With root members full pathWithout root members full path

::: mynamespace.classA
    options:
      show_root_members_full_path: true

`mynamespace.classA` ¤

Docstring of class A.

`mynamespace.classA.method_a()` ¤

Docstring of the method.

::: mynamespace.classA
    options:
      show_root_members_full_path: false

`mynamespace.classA` ¤

Docstring of class A.

`method_a()` ¤

Docstring of the method.

`show_object_full_path`¤

Type bool False

Show the full namespace 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:
      matlab:
        options:
          show_object_full_path: true

or in docs/some_page.md (local configuration)

::: +mynamespace
    options:
      show_object_full_path: false

Preview

With object full pathWithout object full path

::: +mynamespace
    options:
      show_object_full_path: true

`mynamespace` ¤

This is the docstring for mynamespace.

`mynamespace.classB` ¤

Docstring of class B.

`mynamespace.classB.prop_b` ¤

Docstring of the property.

`mynamespace.classB.method_b()` ¤

Docstring of the method.

`mynamespace.classA` ¤

Docstring of class A.

`mynamespace.classA.method_a()` ¤

Docstring of the method.

`mynamespace.typed_function(input, /, *, keyword=0)` ¤

Example function with typed inputs and outputs

Name-Value Arguments:

Name	Type	Description
`keyword`	`double`	An optional keyword argument

::: +mynamespace
    options:
      show_object_full_path: false

`mynamespace` ¤

This is the docstring for mynamespace.

`classB` ¤

Docstring of class B.

`prop_b` ¤

Docstring of the property.

`method_b()` ¤

Docstring of the method.

`classA` ¤

Docstring of class A.

`method_a()` ¤

Docstring of the method.

`typed_function(input, /, *, keyword=0)` ¤

Example function with typed inputs and outputs

Name-Value Arguments:

Name	Type	Description
`keyword`	`double`	An optional keyword argument

`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 object

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:
      matlab:
        options:
          group_by_category: true
          show_category_heading: true

or in docs/some_page.md (local configuration)

::: matlab_callable
    options:
      group_by_category: true
      show_category_heading: false

Source files

tree readme.md classA.m classB.m typed_function.m

📁 +mynamespace
├── 📄 readme.md
├── 📄 classA.m
├── 📄 classB.m
└── 📄 typed_function.m

This is the docstring for mynamespace.

classdef classA
    % Docstring of class A.

    methods
        function obj = method_a(inputArg1)
            % Docstring of the method.
        end
    end
end

classdef classB
    % Docstring of class B.
    properties
        prop_b   % Docstring of the property.
    end
    methods
        function obj = method_b(inputArg1)
            % Docstring of the method.
        end
    end
end

function output = typed_function(input, options)
    % Example function with typed inputs and outputs
    arguments (Input)
        input (1,1) string % The input variable
        options.keyword (1,1) double = 0 % An optional keyword argument
    end
    arguments (Output)
        output (1,:) char % The output variable
    end
    output = char(input);
end

Preview

With category headingsWithout category headings

::: +mynamespace
    options:
      group_by_category: true
      show_category_heading: true

`mynamespace` ¤

This is the docstring for mynamespace.

Classes¤

`classB` ¤

Docstring of class B.

Attributes¤

prop_b ¤

Docstring of the property.

Functions¤

method_b() ¤

Docstring of the method.

`classA` ¤

Docstring of class A.

Functions¤

method_a() ¤

Docstring of the method.

Functions¤

`typed_function(input, /, *, keyword=0)` ¤

Example function with typed inputs and outputs

Name-Value Arguments:

Name	Type	Description
`keyword`	`double`	An optional keyword argument

::: +mynamespace
    options:
      group_by_category: true
      show_category_heading: false

`mynamespace` ¤

This is the docstring for mynamespace.

`classB` ¤

Docstring of class B.

`prop_b` ¤

Docstring of the property.

`method_b()` ¤

Docstring of the method.

`classA` ¤

Docstring of class A.

`method_a()` ¤

Docstring of the method.

`typed_function(input, /, *, keyword=0)` ¤

Example function with typed inputs and outputs

Name-Value Arguments:

Name	Type	Description
`keyword`	`double`	An optional keyword argument

`show_symbol_type_heading`¤

Type bool False

Show the symbol type in headings.

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

in mkdocs.yml (global configuration)

plugins:
- mkdocs-material-matlab # (1)
- mkdocstrings:
    handlers:
      matlab:
        options:
          show_symbol_type_heading: true

When using material theme, make sure to also enable the plugin mkdocs-material-matlab such that the right heading types are displayed. Otherwise, will be shown as attr and will be shown as mod, as the mkdocstrings-matlab plugin is reusing assets from mkdocstrings-python.

or in docs/some_page.md (local configuration)

::: matlab_callable
    options:
      show_symbol_type_heading: false

Source files

tree readme.md classA.m classB.m typed_function.m

📁 +mynamespace
├── 📄 readme.md
├── 📄 classA.m
├── 📄 classB.m
└── 📄 typed_function.m

This is the docstring for mynamespace.

classdef classA
    % Docstring of class A.

    methods
        function obj = method_a(inputArg1)
            % Docstring of the method.
        end
    end
end

classdef classB
    % Docstring of class B.
    properties
        prop_b   % Docstring of the property.
    end
    methods
        function obj = method_b(inputArg1)
            % Docstring of the method.
        end
    end
end

function output = typed_function(input, options)
    % Example function with typed inputs and outputs
    arguments (Input)
        input (1,1) string % The input variable
        options.keyword (1,1) double = 0 % An optional keyword argument
    end
    arguments (Output)
        output (1,:) char % The output variable
    end
    output = char(input);
end

Preview

With symbol type in headingsWithout symbol type in headings

::: +mynamespace
    options:
      show_symbol_type_heading: true

`mynamespace` ¤

This is the docstring for mynamespace.

`classB` ¤

Docstring of class B.

`prop_b` ¤

Docstring of the property.

`method_b()` ¤

Docstring of the method.

`classA` ¤

Docstring of class A.

`method_a()` ¤

Docstring of the method.

`typed_function(input, /, *, keyword=0)` ¤

Example function with typed inputs and outputs

Name-Value Arguments:

Name	Type	Description
`keyword`	`double`	An optional keyword argument

::: +mynamespace
    options:
      show_symbol_type_heading: false

`mynamespace` ¤

This is the docstring for mynamespace.

`classB` ¤

Docstring of class B.

`prop_b` ¤

Docstring of the property.

`method_b()` ¤

Docstring of the method.

`classA` ¤

Docstring of class A.

`method_a()` ¤

Docstring of the method.

`typed_function(input, /, *, keyword=0)` ¤

Example function with typed inputs and outputs

Name-Value Arguments:

Name	Type	Description
`keyword`	`double`	An optional keyword argument

`show_symbol_type_toc`¤

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.

in mkdocs.yml (global configuration)

plugins:
- mkdocs-material-matlab # (1)
- mkdocstrings:
    handlers:
      matlab:
        options:
          show_symbol_type_toc: true

When using material theme, make sure to also enable the plugin mkdocs-material-matlab such that the right heading types are displayed. Otherwise, will be shown as attr and will be shown as mod, as the mkdocstrings-matlab plugin is reusing assets from mkdocstrings-python.

or in docs/some_page.md (local configuration)

::: matlab_callable
    options:
      show_symbol_type_toc: false

Preview

With symbol type in ToCWithout symbol type in ToC

namespace
function
Class
- method
- property

namespace
function
Class
- method
- property

Headings options¤

heading_level¤

mynamespace (3)

ClassA (4)

ClassB (4)

myfunction (5)

ClassA (3)

ClassB (3)

myfunction (4)

parameter_headings¤

mynamespace.typed_function(input, /, *, keyword=0) ¤

input ¤

mynamespace.typed_function(input, /, *, keyword=0) ¤

input ¤

input ¤

input ¤

show_root_heading¤

mynamespace.classA ¤

method_a() ¤

mynamespace.classB ¤

prop_b ¤

method_b() ¤

method_a() ¤

prop_b ¤

method_b() ¤

show_root_toc_entry¤

show_root_full_path¤

mynamespace.classA ¤

method_a() ¤

classA ¤

method_a() ¤

show_root_members_full_path¤

mynamespace.classA ¤

mynamespace.classA.method_a() ¤

mynamespace.classA ¤

method_a() ¤

show_object_full_path¤

mynamespace ¤

mynamespace.classB ¤

mynamespace.classB.prop_b ¤

mynamespace.classB.method_b() ¤

mynamespace.classA ¤

mynamespace.classA.method_a() ¤

mynamespace.typed_function(input, /, *, keyword=0) ¤

mynamespace ¤

classB ¤

prop_b ¤

method_b() ¤

classA ¤

method_a() ¤

typed_function(input, /, *, keyword=0) ¤

show_category_heading¤

mynamespace ¤

Classes¤

classB ¤

Attributes¤

Functions¤

classA ¤

Functions¤

Functions¤

typed_function(input, /, *, keyword=0) ¤

mynamespace ¤

classB ¤

prop_b ¤

method_b() ¤

classA ¤

method_a() ¤

typed_function(input, /, *, keyword=0) ¤

show_symbol_type_heading¤

mynamespace ¤

classB ¤

prop_b ¤

method_b() ¤

classA ¤

method_a() ¤

typed_function(input, /, *, keyword=0) ¤

mynamespace ¤

classB ¤

prop_b ¤

method_b() ¤

`heading_level`¤

`mynamespace` (3)

`ClassA` (4)

`ClassB` (4)

`myfunction` (5)

`ClassA` (3)

`ClassB` (3)

`myfunction` (4)

`parameter_headings`¤

`mynamespace.typed_function(input, /, *, keyword=0)` ¤

`input` ¤

`mynamespace.typed_function(input, /, *, keyword=0)` ¤

`input` ¤

`input` ¤

`input` ¤

`show_root_heading`¤

`mynamespace.classA` ¤

`method_a()` ¤

`mynamespace.classB` ¤

`prop_b` ¤

`method_b()` ¤

`method_a()` ¤

`prop_b` ¤

`method_b()` ¤

`show_root_toc_entry`¤

`show_root_full_path`¤

`mynamespace.classA` ¤

`method_a()` ¤

`classA` ¤

`method_a()` ¤

`show_root_members_full_path`¤

`mynamespace.classA` ¤

`mynamespace.classA.method_a()` ¤

`mynamespace.classA` ¤

`method_a()` ¤

`show_object_full_path`¤

`mynamespace` ¤

`mynamespace.classB` ¤

`mynamespace.classB.prop_b` ¤

`mynamespace.classB.method_b()` ¤

`mynamespace.classA` ¤

`mynamespace.classA.method_a()` ¤

`mynamespace.typed_function(input, /, *, keyword=0)` ¤

`mynamespace` ¤

`classB` ¤

`prop_b` ¤

`method_b()` ¤

`classA` ¤

`method_a()` ¤

`typed_function(input, /, *, keyword=0)` ¤

`show_category_heading`¤

`mynamespace` ¤

`classB` ¤

`classA` ¤

`typed_function(input, /, *, keyword=0)` ¤

`mynamespace` ¤

`classB` ¤

`prop_b` ¤

`method_b()` ¤

`classA` ¤

`method_a()` ¤

`typed_function(input, /, *, keyword=0)` ¤

`show_symbol_type_heading`¤

`mynamespace` ¤

`classB` ¤

`prop_b` ¤

`method_b()` ¤

`classA` ¤

`method_a()` ¤

`typed_function(input, /, *, keyword=0)` ¤

`mynamespace` ¤

`classB` ¤

`prop_b` ¤

`method_b()` ¤

`classA` ¤

`method_a()` ¤

`typed_function(input, /, *, keyword=0)` ¤

`show_symbol_type_toc`¤