Usage

Installation

You can install this handler by specifying it as a dependency:

pyproject.toml

# PEP 621 dependencies declaration
# adapt to your dependencies manager
[project]
dependencies = [
    "mkdocstrings-matlab>=0.X.Y",
]

Configuration

For mkdocstrings the default will be the Python handler. You can change the default handler, or explicitely set the MATLAB handler as default by defining the default_handler configuration option of mkdocstrings in mkdocs.yml:

mkdocs.yml

plugins:
- mkdocstrings:
    default_handler: matlab
    matlab:
        ...  # the MATLAB handler configuration

When using the material theme, it is best to also configure the mkdocs_material_matlab plugin. This additional plugin, which is installed together with mkdocstrings-matlab, will overrule the symbols shown with show_symbol_type_heading and show_symbol_type_toc to show the correct symbols as per MATLAB nomenclature.

mkdocs.yml

plugins:
- mkdocs_material_matlab
- mkdocstrings:
    default_handler: matlab
    matlab:
        ...  # the MATLAB handler configuration

I want to document both MATLAB and Python

The mkdocs_material_matlab plugin will also change the symbols for the Python handler. This means that Python modules will not be tagged with symbol mod but name (namespace), and attributes are not tagged with symbol attr but prop (property).

Injecting documentation

With the MATLAB handler installed and configured as default handler, you can inject documentation for a module, class, function, or any other MATLAB object with mkdocstrings' [autodoc syntax], in your Markdown pages:

::: path.to.object

If another handler was defined as default handler, you can explicitely ask for the MATLAB handler to be used when injecting documentation with the handler option:

::: path.to.object
    handler: matlab

Entire namespaces can be fully documented by prefixing the + character to the namespace that is to be documented. E.g. the following namespace

📁 +mynamespace
├── 📄 Contents.m
├── 📄 readme.md
├── 📄 myclass.m
└── 📁 +subnamespace
    └── 📄 mfunction.m

is documented with:

::: +mynamespace

The docstring of the namespace is taken from either the Contents.m or a readme.md that resides at the root level of the namespace, with Contents.m taking precedence over readme.md.

Documenting a nested namespace requires only a single prefixed + at the start of the fully resolved path, e.g.

::: +mynamespace.subnamespace

Global-only options

Some options are global only, and go directly under the handler's name.

paths

This option is used to set the MATLAB search path. The MATLAB search path is a subset of all the folders in the file system. The order of folders on the search path is important. When files with the same name appear in multiple folders on the search path, MATLAB uses the one found in the folder nearest to the top of the search path.

Non-absolute paths are computed as relative to MkDocs configuration file. Example:

mkdocs.yml

plugins:
- mkdocstrings:
    handlers:
      matlab:
        paths: [src]  # search files in the src folder

paths_recursive

This option allows you to specify whether the handler should recursively search through the directories specified in the paths option. When set to true, the handler will look for MATLAB files in all subdirectories of the specified paths.

Example:

mkdocs.yml

plugins:
- mkdocstrings:
    handlers:
      matlab:
        paths: [src]  # search files in the src folder
        paths_recursive: true  # search recursively in subfolders

Global/local options

The other options can be used both globally and locally, under the options key. For example, globally:

mkdocs.yml

plugins:
- mkdocstrings:
    handlers:
      matlab:
        options:
          do_something: true

...and locally, overriding the global configuration:

docs/some_page.md

::: package.module.class
    options:
      do_something: false

These options affect how the documentation is collected from sources and rendered. See the following tables summarizing the options, and get more details for each option in the following pages:

• General options: various options that do not fit in the other categories
• Headings options: options related to headings and the table of contents (or sidebar, depending on the theme used)
• Members options: options related to filtering or ordering members in the generated documentation
• Docstrings options: options related to docstrings (parsing and rendering)
• Signature options: options related to signatures and type annotations

Options summary

Default handler configuration.

General options:

• show_bases (bool) –

  Show the base classes of a class. Default: True.

• show_inheritance_diagram (bool) –

  Show the inheritance diagram of a class using Mermaid. Default: False.

• show_source (bool) –

  Show the source code of this object. Default: True.

Headings options:

• heading_level (int) –

  The initial heading level to use. Default: 2.

• parameter_headings (bool) –

  Whether to render headings for parameters (therefore showing parameters in the ToC). Default: False.

• show_root_heading (bool) –

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

• show_root_toc_entry (bool) –

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

• show_root_full_path (bool) –

  Show the full path for the root object heading. Default: True.

• show_root_members_full_path (bool) –

  Show the full path of the root members. Default: False.

• show_object_full_path (bool) –

  Show the full path of every object. Default: False.

• show_category_heading (bool) –

  When grouped by categories, show a heading for each category. Default: False.

• show_symbol_type_heading (bool) –

  Show the symbol type in headings (e.g. mod, class, meth, func and attr). Default: False.

• show_symbol_type_toc (bool) –

  Show the symbol type in the Table of Contents (e.g. mod, class, methd, func and attr). Default: False.

Members options:

• members (list[str] | bool | None) –

  A boolean, or an explicit list of members to render. If true, select all members without further filtering. If false or empty list, do not render members. If none, select all members and apply further filtering with filters and docstrings. Default: None.

• hidden_members (list[str] | bool | None) –

  A boolean, or an explicit list of hidden members to render. If true, select all inherited members, which can then be filtered with members. If false or empty list, do not select any hidden member. Default: False.

• private_members (list[str] | bool | None) –

  A boolean, or an explicit list of private members to render. If true, select all inherited members, which can then be filtered with members. If false or empty list, do not select any private member. Default: False.

• inherited_members (list[str] | bool | None) –

  A boolean, or an explicit list of inherited members to render. If true, select all inherited members, which can then be filtered with members. If false or empty list, do not select any inherited member. Default: False.

• members_order (str) –

  The members ordering to use. Options: alphabetical - order by the members names, source - order members as they appear in the source file. Default: "alphabetical".

• filters (list[str] | None) –

  A list of filters applied to filter objects based on their name. A filter starting with ! will exclude matching objects instead of including them. The members option takes precedence over filters (filters will still be applied recursively to lower members in the hierarchy). Default: ["!^delete$|^disp$"].

• group_by_category (bool) –

  Group the object's children by categories: properties, classes, functions, and namespaces. Default: True.

• show_subnamespaces (bool) –

  When rendering a namespace, show its subnamespaces recursively. Default: False.

• summary (bool | dict[str, bool]) –

  Whether to render summaries of namespaces, classes, functions (methods) and properties. Default: False.

• show_labels (bool) –

  Whether to show labels of the members. Default: True.

Docstrings options:

• docstring_style (str) –

  The docstring style to use: google, numpy, sphinx, or None. Default: "google".

• docstring_options (dict) –

  The options for the docstring parser. See docstring parsers and their options in Griffe docs.

• docstring_section_style (str) –

  The style used to render docstring sections. Options: table, list, spacy. Default: "table".

• parse_arguments (bool) –

  Whether to load inputs and output parameters based on argument validation blocks. Default: True.

• merge_constructor_into_class (bool) –

  Whether to merge the constructor method into the class' signature and docstring. Default: False.

• merge_constructor_ignore_summary (bool) –

  Whether to ignore the constructor summary when merging it into the class. Default: False.

• show_if_no_docstring (bool) –

  Show the object heading even if it has no docstring or children with docstrings. Default: False.

• show_docstring_properties (bool) –

  Whether to display the "Properties" section in the object's docstring. Default: True.

• show_docstring_functions (bool) –

  Whether to display the "Functions" or "Methods" sections in the object's docstring. Default: True.

• show_docstring_classes (bool) –

  Whether to display the "Classes" section in the object's docstring. Default: True.

• show_docstring_namespaces (bool) –

  Whether to display the "Namespaces" section in the object's docstring. Default: True.

• show_docstring_description (bool) –

  Whether to display the textual block (including admonitions) in the object's docstring. Default: True.

• show_docstring_examples (bool) –

  Whether to display the "Examples" section in the object's docstring. Default: True.

• show_docstring_input_arguments (bool) –

  Whether to display the "Input arguments" section in the object's docstring. Default: True.

• show_docstring_name_value_arguments (bool) –

  Whether to display the "Name-value pairs" section in the object's docstring. Default: True.

• show_docstring_output_arguments (bool) –

  Whether to display the "Output arguments" section in the object's docstring. Default: True.

Signatures/annotations options:

• show_signature (bool) –

  Show methods and functions signatures. Default: True.

• show_signature_annotations (bool) –

  Show the type annotations in methods and functions signatures. Default: False.

• separate_signature (bool) –

  Whether to put the whole signature in a code block below the heading.

• signature_crossrefs (bool) –

  Whether to render cross-references for type annotations in signatures. Default: False.