Docstrings options

docstring_style

• Type str "google"

The docstring style to expect when parsing docstrings.

Possible values:

• "google": see Google style.
• "numpy": see Numpy style.
• "sphinx": see Sphinx style.
• None (null or ~ in YAML): no style at all, parse as regular text.

in mkdocs.yml (global configuration)

plugins:
- mkdocstrings:
    handlers:
      matlab:
        options:
          docstring_style: google

or in docs/some_page.md (local configuration)

::: matlab_callable
    options:
      docstring_style: numpy

Preview

Every style gets rendered the same way. Here are some docstring examples.

GoogleNumpySphinx

function message = greet(name)
    % Greet someone.
    %  
    % Parameters:
    %     name: The name of the person to greet.
    % 
    % Returns:
    %     message: A greeting message.

    message = sprintf("Hello %s!", name)
end

function message = greet(name)
    % Greet someone.
    %  
    % Parameters
    % ----------
    % name
    %    The name of the person to greet.
    % 
    % Returns
    % -------
    % message
    %    A greeting message.

    message = sprintf("Hello %s!", name)
end

function message = greet(name)
    % Greet someone.
    %  
    % :param name: The name of the person to greet.
    % :return: A greeting message.

    message = sprintf("Hello %s!", name)
end

docstring_options

• Type dict {}

The options for the docstring parser.

• Google-style options
• Numpydoc-style options

The Sphinx style does not offer any option.

Most of the options in the linked pages will not have an effect to mkdocstrings-matlab, since here the objects are mocked as Python objects are docstrings are injected into the mocked objects.

in mkdocs.yml (global configuration)

plugins:
- mkdocstrings:
    handlers:
      matlab:
        options:
          docstring_options:
            warn_unknown_params: false

or in docs/some_page.md (local configuration)

::: matlab_callable
    options:
      docstring_options:
        warn_unknown_params: false

docstring_section_style

• Type str "table"

The style used to render docstring sections.

A section is a block of text that has a special meaning in a docstring. There are sections for documenting attributes of an object, parameters of a function, exceptions raised by a function, the return value of a function, etc.

Sections are parsed as structured data and can therefore be rendered in different ways. Possible values:

• "table": a simple table, usually with type, name and description columns
• "list": a simple list, akin to what you get with the [ReadTheDocs Sphinx theme]{ .external }
• "spacy": a poor implementation of the amazing tables in [Spacy's documentation]{ .external }

in mkdocs.yml (global configuration)

plugins:
- mkdocstrings:
    handlers:
      matlab:
        options:
          docstring_section_style: table

or in docs/some_page.md (local configuration)

::: matlab_callable
    options:
      docstring_section_style: list

Preview

TableListSpacy

Tables work well when you have lots of items with short names, type annotations, descriptions, etc.. With longer strings, the columns risk getting squished horizontally. In that case, the Spacy tables can help.

Parameters:

Type	Name	Description	Default
int	threshold	Threshold for something.	required
bool	flag	Enable something.	False

Other Parameters:

Type	Name	Description	Default
list[int | float]	gravity_forces	Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.	required
VacuumType | Literal["regular"]	vacuum_type	Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.	VacuumType.PLASMA

Lists work well whatever the length of names, type annotations, descriptions, etc.

Parameters:

• threshold (int) — Threshold for something.
• flag (bool) — Enable something.

Other Parameters:

• gravity_forces (list[int | float]) — Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
• vacuum_type (VacuumType | Literal["regular"]) — Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Spacy tables work better than regular tables with longer names, type annotations, descriptions, etc., by reserving more horizontal space on the second column.

Parameters:

Name	Description
threshold	Threshold for something. TYPE: int DEFAULT: required
flag	Enable something. TYPE: bool DEFAULT: False

Other Parameters:

Name	Description
gravity_forces	Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. TYPE: list[int | float] DEFAULT: required
vacuum_type	Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. TYPE:VacuumType | Literal["regular"] DEFAULT: VacuumType.PLASMA

parse_arguments

• Type bool True

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

Similarly to Python, MATLAB is by default not a typed language. Function and method arguments are dynamically typed, in most cases. This provides flexibility, but is generally bad behavior if the code is meant for production or is intended to be exposed as an API.

In MATLAB R2019b the concept of Argument Definitions was introduced. Within an arguments block, the type, size, or other aspects of the inputs (and outputs since R2022b) can be verified.

function z = mySharedFunction(x,y,NameValueArgs)
   arguments
      x (1,1) double     % scalar
      y double {mustBeVector,mustBePositive} 
      NameValueArgs.A string
      NameValueArgs.B string = "default"
   end 
...
end

The mkdocstrings-matlab plugin is able to parse the argument blocks and extract the type and default information, and any comment after each Argument Definition will be parsed as the argument docstring. If if parse_arguments is enabled, sections will be rendered for the parameters, name-value pairs and the return arguments of functions and methods. These sections can be individually toggled with show_docstring_input_arguments, show_docstring_name_value_arguments and show_docstring_output_arguments.

in mkdocs.yml (global configuration)

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

or in docs/some_page.md (local configuration)

::: mynamespace.typed_function
    options:
      parse_arguments: 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

Parse argument validationDon't parse argument validation

::: mynamespace.typed_function
    options:
      parse_arguments: true

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

Example function with typed inputs and outputs

Parameters:

Name	Type	Description	Default
input	string	The input variable	required

Name-Value Arguments:

Name	Type	Description
keyword	double	An optional keyword argument

Returns:

Name	Type	Description
output	char	The output variable

::: mynamespace.typed_function
    options:
      parse_arguments: false

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

Example function with typed inputs and outputs

Note

Prior to MATLAB R2019b, the functionality of the arguments blocks was most commonly achieved through inputParser. The validations created with inputParser will not be parsed by mkdocstrings-matlab, since it does not have a strict syntax as opposed to Argument Definitions.

merge_constructor_into_class

• Type bool False

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

By default, only the class name is rendered in headings. When merging, the constructor method parameters are added after the class name, like a signature, and the constructor method docstring is appended to the class' docstring. This option is well used in combination with the merge_constructor_ignore_summary option, to discard the first line of the constructor docstring which is not often useful.

in mkdocs.yml (global configuration)

plugins:
- mkdocstrings:
    handlers:
      matlab:
        options:
          merge_constructor_into_class: true
          merge_constructor_ignore_summary: true

or in docs/some_page.md (local configuration)

::: matlab_callable
    options:
      merge_constructor_into_class: true
      merge_constructor_ignore_summary: true

Thing.m

classdef Thing
% Class docstring

methods 
    function obj = Thing(value)
        % Initialize a thing.
        arguments
            value % The thing's value.
        end
        obj.value = value;
    end
end

properties (Access = private)
    value % The thing's value.
end

end

Preview

Merged, summary discardedMerged, summary keptUnmerged

::: Thing
    options:
      merge_constructor_into_class: true
      merge_constructor_ignore_summary: true

Thing

Class docstring

Parameters:

Name	Type	Description	Default
value		The thing's value.	required

::: Thing
    options:
      merge_constructor_into_class: true
      merge_constructor_ignore_summary: false

Thing

Class docstring

Initialize a thing.

Parameters:

Name	Type	Description	Default
value		The thing's value.	required

::: Thing
    options:
      merge_constructor_into_class: false

Thing

Class docstring

Thing(value)

Initialize a thing.

Parameters:

Name	Type	Description	Default
value		The thing's value.	required

show_if_no_docstring

• Type bool False

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

Without an explicit list of members, members are selected based on filters, and then filtered again to keep only those with docstrings. Checking if a member has a docstring is done recursively: if at least one of its direct or indirect members (lower in the tree) has a docstring, the member is rendered. If the member does not have a docstring, and none of its members have a docstring, it is excluded.

With this option you can tell the Python handler to skip the docstring check.

in mkdocs.yml (global configuration)

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

or in docs/some_page.md (local configuration)

::: +undocumented
    options:
      show_if_no_docstring: true

Source files

tree ClassWithoutDocstring.m function_with_docstring.m function_without_docstring.m

📁 +undocumented
├── 📄 ClassWithoutDocstring.m
├── 📄 function_with_docstring.m
└── 📄 function_without_docstring.m

classdef ClassWithoutDocstring
    methods
        function obj = method_without_docstring(obj)
        end

        function obj = method_with_docstring(obj)
            % Hello
        end
    end
end

function function_with_docstring()
    % Hello
end

function function_without_docstring()
end

Preview

ShowDon't show

::: +undocumented
    options:
      show_if_no_docstring: true

undocumented

ClassWithoutDocstring

method_without_docstring()

method_with_docstring()

Hello

function_without_docstring()

function_with_docstring()

Hello

::: +undocumented
    options:
      show_if_no_docstring: false

undocumented

ClassWithoutDocstring

method_with_docstring()

Hello

function_with_docstring()

Hello

show_docstring_properties

• Type bool True

Whether to render the "Properties" sections of docstrings.

in mkdocs.yml (global configuration)

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

or in docs/some_page.md (local configuration)

::: matlab_callable
    options:
      show_docstring_properties: false

Class.m

classdef Class
    % Summary.
    %
    % Long description.
    %
    % Warning: Deprecated
    %     Stop using this class.
    %
    % Properties:
    %     attr: Some attribute.

    properties
        attr int = 1
    end
end

Preview

With propertiesWithout properties

::: Class
    options:
      show_docstring_properties: true

Class

Summary.

Long description.

Deprecated

Stop using this class.

Properties:

Name	Type	Description
attr		Some attribute.

::: Class
    options:
      show_docstring_properties: false

Class

Summary.

Long description.

Deprecated

Stop using this class.

show_docstring_functions

• Type bool True

Whether to render the "Functions" or "Methods" sections of docstrings.

in mkdocs.yml (global configuration)

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

or in docs/some_page.md (local configuration)

::: path.to.module
    options:
      show_docstring_functions: false

Source files

tree readme.md do_something.m aClass.m subfunction.m Contents.m

📁 +module
├── 📁 +submodule
│   ├── 📄 Contents.m
│   └── 📄 subfunction.m
├── 📄 aClass.m
├── 📄 do_something.m
└── 📄 readme.m

Docstring of module.

Functions:
    do_something: Do something.

Classes:
    aClass: Summary

Namespaces:
    submodule: This is a submodule

function do_something()
% Do something.
end

classdef aClass
    % Summary.
    %
    % Long description.
    %
    % Methods:
    %     foo: Some method.

    methods
        function foo()
            % Summary.
        end
    end
end

function subfunction
    % This is a subfunction.
end

% This is a submodule

Preview

With methodsWithout methodsWith functionsWithout functions

::: module.aClass
    options:
      show_docstring_functions: true

module.aClass

Summary.

Long description.

Methods:

Name	Description
foo	Some method.

foo()

Summary.

::: module.aClass
    options:
      show_docstring_functions: false

module.aClass

Summary.

Long description.

foo()

Summary.

::: +module
    options:
      show_docstring_functions: true
      members: false

module

Docstring of module.

Functions:

Name	Description
do_something	Do something.

Classes:

Name	Description
aClass	Summary

Namespaces:

Name	Description
submodule	This is a submodule

::: +module
    options:
      show_docstring_functions: false
      members: false

module

Docstring of module.

Classes:

Name	Description
aClass	Summary

Namespaces:

Name	Description
submodule	This is a submodule

show_docstring_classes

• Type bool True

Whether to render the "Classes" sections of docstrings.

in mkdocs.yml (global configuration)

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

or in docs/some_page.md (local configuration)

::: +matlab_namespace
    options:
      show_docstring_classes: false

Source files

tree readme.md do_something.m aClass.m subfunction.m Contents.m

📁 +module
├── 📁 +submodule
│   ├── 📄 Contents.m
│   └── 📄 subfunction.m
├── 📄 aClass.m
├── 📄 do_something.m
└── 📄 readme.m

Docstring of module.

Functions:
    do_something: Do something.

Classes:
    aClass: Summary

Namespaces:
    submodule: This is a submodule

function do_something()
% Do something.
end

classdef aClass
    % Summary.
    %
    % Long description.
    %
    % Methods:
    %     foo: Some method.

    methods
        function foo()
            % Summary.
        end
    end
end

function subfunction
    % This is a subfunction.
end

% This is a submodule

Preview

With classesWithout classes

::: +module
    options:
      show_docstring_classes: true
      members: false

module

Docstring of module.

Functions:

Name	Description
do_something	Do something.

Classes:

Name	Description
aClass	Summary

Namespaces:

Name	Description
submodule	This is a submodule

::: +module
    options:
      show_docstring_classes: false
      members: false

module

Docstring of module.

Functions:

Name	Description
do_something	Do something.

Namespaces:

Name	Description
submodule	This is a submodule

show_docstring_namespaces

• Type bool True

Whether to render the "Namespaces" sections of docstrings.

in mkdocs.yml (global configuration)

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

or in docs/some_page.md (local configuration)

::: +matlab_namespace
    options:
      show_docstring_namespaces: false

Source files

tree readme.md do_something.m aClass.m subfunction.m Contents.m

📁 +module
├── 📁 +submodule
│   ├── 📄 Contents.m
│   └── 📄 subfunction.m
├── 📄 aClass.m
├── 📄 do_something.m
└── 📄 readme.m

Docstring of module.

Functions:
    do_something: Do something.

Classes:
    aClass: Summary

Namespaces:
    submodule: This is a submodule

function do_something()
% Do something.
end

classdef aClass
    % Summary.
    %
    % Long description.
    %
    % Methods:
    %     foo: Some method.

    methods
        function foo()
            % Summary.
        end
    end
end

function subfunction
    % This is a subfunction.
end

% This is a submodule

Preview

With namespacesWithout namespaces

::: +module
    options:
      show_docstring_namespaces: true
      members: false

module

Docstring of module.

Functions:

Name	Description
do_something	Do something.

Classes:

Name	Description
aClass	Summary

Namespaces:

Name	Description
submodule	This is a submodule

::: +module
    options:
      show_docstring_namespaces: false
      members: false

module

Docstring of module.

Functions:

Name	Description
do_something	Do something.

Classes:

Name	Description
aClass	Summary

show_docstring_description

• Type bool True

Whether to render the textual blocks (including admonitions) of docstrings.

in mkdocs.yml (global configuration)

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

or in docs/some_page.md (local configuration)

::: matlab_callable
    options:
      show_docstring_description: false

Class.m

classdef Class
    % Summary.
    %
    % Long description.
    %
    % Warning: Deprecated
    %     Stop using this class.
    %
    % Properties:
    %     attr: Some attribute.

    properties
        attr int = 1
    end
end

Preview

With description blocksWithout description blocks

::: Class
    options:
      show_docstring_description: true

Class

Summary.

Long description.

Deprecated

Stop using this class.

Properties:

Name	Type	Description
attr		Some attribute.

::: Class
    options:
      show_docstring_description: false

Class

Properties:

Name	Type	Description
attr		Some attribute.

show_docstring_examples

• Type bool True

Whether to render the "Examples" sections of docstrings.

in mkdocs.yml (global configuration)

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

or in docs/some_page.md (local configuration)

::: matlab_callable
    options:
      show_docstring_examples: false

print_hello.m

function print_hello()
    % Print hello.
    %
    % Examples:
    %     >>> print("hello")
    %     % hello
    fprintf("hello\n")
end

Preview

With examplesWithout examples

::: print_hello
    options:
      show_docstring_examples: true

print_hello()

Print hello.

Examples:

>>> print("hello")
% hello

::: print_hello
    options:
      show_docstring_examples: false

print_hello()

Print hello.

show_docstring_input_arguments

• Type bool True

Whether to render the "Parameters" sections of docstrings. The accepted title headings are inputs or input arguments (case-insensitive).

in mkdocs.yml (global configuration)

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

or in docs/some_page.md (local configuration)

::: matlab_callable
    options:
      show_docstring_input_arguments: false

do_something.m

function do_something(whatever)
% Do something.
%
% Parameters:
%     whatever: Some integer.
    arguments
        whatever (1,1) double {mustBeInteger} = 1 % A integer
    end
end

Preview

With parametersWithout parameters

::: do_something
    options:
      show_docstring_input_arguments: true

do_something(whatever=1)

Do something.

Input arguments:

Name	Type	Description	Default
whatever		Some integer.	required

::: do_something
    options:
      show_docstring_input_arguments: false

do_something(whatever=1)

Do something.

Warning

If a Input arguments section is provided in the docstring, the description here will overule the parsed values from the argument validation block (see parse_arguments).

show_docstring_name_value_arguments

• Type bool True

Whether to render the "Name-value pairs" sections of docstrings. The accepted title headings are name-value pairs or name-value arguments (case-insensitive).

in mkdocs.yml (global configuration)

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

or in docs/some_page.md (local configuration)

::: matlab_callable
    options:
      show_docstring_name_value_arguments: false

do_varargin.m

function do_varargin(varargin)
% Do something.
%
% Name-Value pairs:
%     whatever: Some value.
end

Preview

With parametersWithout parameters

::: do_varargin
    options:
      show_docstring_name_value_arguments: true

do_varargin(varargin)

Do something.

Name-Value Arguments:

Name	Type	Description
whatever		Some value.

::: do_varargin
    options:
      show_docstring_name_value_arguments: false

do_varargin(varargin)

Do something.

Warning

If a Name-value arguments section is provided in the docstring, the description here will overule the parsed values from the argument validation block (see parse_arguments).

show_docstring_output_arguments

• Type bool True

Whether to render the "Returns" sections of docstrings. The accepted title headings are outputs or output arguments (case-insensitive).

in mkdocs.yml (global configuration)

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

or in docs/some_page.md (local configuration)

::: matlab_callable
    options:
      show_docstring_output_arguments: false

do_output.m

function value = do_output()
% Do something.
%
% outputs:
%     value: Some value.
end

Preview

With parametersWithout parameters

::: do_output
    options:
      show_docstring_output_arguments: true

do_output()

Do something.

Output arguments:

Name	Type	Description
value		Some value.

::: do_output
    options:
      show_docstring_output_arguments: false

do_output()

Do something.

Warning

If a Output arguments section is provided in the docstring, the description here will overule the parsed values from the argument validation block (see parse_arguments).