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(nullor~in YAML): no style at all, parse as regular text.
plugins:
- mkdocstrings:
handlers:
matlab:
options:
docstring_style: google
[project.plugins.mkdocstrings.handlers.matlab.options]
docstring_style = "google"
::: matlab_callable
options:
docstring_style: numpy
Preview
Every style gets rendered the same way. Here are some docstring examples.
docstring_options¤
- Type
dict{}
The options for the docstring parser.
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.
plugins:
- mkdocstrings:
handlers:
matlab:
options:
docstring_options:
warn_unknown_params: false
[project.plugins.mkdocstrings.handlers.matlab.options]
docstring_options = { warn_unknown_params = false }
::: 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 }
plugins:
- mkdocstrings:
handlers:
matlab:
options:
docstring_section_style: table
[project.plugins.mkdocstrings.handlers.matlab.options]
docstring_section_style = "table"
::: matlab_callable
options:
docstring_section_style: list
Preview
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.
Input arguments:
| Type | Name | Description | Default |
|---|---|---|---|
int |
threshold |
Threshold for something. | required |
bool |
flag |
Enable something. | False |
Name-value arguments:
| 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.
Input arguments:
Name-value arguments:
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.
Input arguments:
| Name | Description |
|---|---|
threshold |
Threshold for something. TYPE: int DEFAULT: required |
flag |
Enable something. TYPE: bool DEFAULT: False |
Name-value arguments:
| 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
boolTrue
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.
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.
plugins:
- mkdocstrings:
handlers:
matlab:
options:
parse_arguments: true
[project.plugins.mkdocstrings.handlers.matlab.options]
parse_arguments = true
::: mynamespace.typed_function
options:
parse_arguments: true
Source files
+mynamespace
readme.md
classA.m
classB.m
typed_function.m
typed_class_property.m
myscript.m
% This is an example script.
% This is a paragraph.
;
Preview: Cross-references
::: mynamespace.typed_function
options:
parse_arguments: true
mynamespace.typed_function(input, keyword=0)
¤
Example function with typed inputs and outputs
Input arguments:
| Name | Type | Description | Default |
|---|---|---|---|
input
|
string
|
The input variable |
required |
Name-value arguments:
| Name | Type | Description | Default |
|---|---|---|---|
keyword
|
double
|
An optional keyword argument |
0
|
Output arguments:
| 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.
Name-value arguments from class properties¤
Since MATLAB R2021b, name-value arguments can be validated against the properties of a class, instead of specifying each property individually:
The name-value argument is parsed with the struct name (opts) as the argument name, and the class path (mynamespace.classA) as its type. When signature_crossrefs is enabled, the type is cross-referenced to the collected class.
Preview: Name-value arguments from class properties
::: mynamespace.typed_class_property
options:
parse_arguments: true
show_signature_types: true
separate_signature: true
signature_crossrefs: true
mynamespace.typed_class_property ¤
(opts: mynamespace.classA)
Example function with name-value arguments from a class property.
Examples¤
= ;Name-value arguments:
| Name | Type | Description | Default |
|---|---|---|---|
opts
|
mynamespace.classA
|
Name-value arguments matching the properties of |
Output arguments:
| Name | Type | Description |
|---|---|---|
output
|
char
|
The output variable |
merge_constructor_into_class¤
- Type
boolFalse
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.
plugins:
- mkdocstrings:
handlers:
matlab:
options:
merge_constructor_into_class: true
[project.plugins.mkdocstrings.handlers.matlab.options]
merge_constructor_into_class = true
::: matlab_callable
options:
merge_constructor_into_class: true
Thing.m
Preview
::: Thing
options:
merge_constructor_into_class: true
parse_arguments: true
Thing(value)
¤
Class docstring
Initialize a thing.
Input arguments:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
The thing's value. |
required |
show_if_no_docstring¤
- Type
boolFalse
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.
plugins:
- mkdocstrings:
handlers:
matlab:
options:
show_if_no_docstring: false
[project.plugins.mkdocstrings.handlers.matlab.options]
show_if_no_docstring = false
::: +undocumented
options:
show_if_no_docstring: true
Source files
+undocumented
ClassWithoutDocstring.m
function_with_docstring.m
function_without_docstring.m
Preview
::: +undocumented
options:
show_if_no_docstring: true
show_docstring_properties¤
- Type
boolTrue
Whether to render the "Properties" sections of docstrings.
plugins:
- mkdocstrings:
handlers:
matlab:
options:
show_docstring_properties: true
[project.plugins.mkdocstrings.handlers.matlab.options]
show_docstring_properties = true
::: matlab_callable
options:
show_docstring_properties: false
Class.m
Preview
show_docstring_functions¤
- Type
boolTrue
Whether to render the "Functions" or "Methods" sections of docstrings.
plugins:
- mkdocstrings:
handlers:
python:
options:
show_docstring_functions: true
[project.plugins.mkdocstrings.handlers.python.options]
show_docstring_functions = true
::: path.to.module
options:
show_docstring_functions: false
Source files
+module
+submodule
Contents.m
subfunction.m
aClass.m
do_something.m
readme.m
Functions:
do_something: Do something.
Classes:
aClass: Summary
Namespaces:
submodule: This is a submodule
% This is a submodulePreview
::: module.aClass
options:
show_docstring_functions: true
::: module.aClass
options:
show_docstring_functions: false
::: +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 |
show_docstring_classes¤
- Type
boolTrue
Whether to render the "Classes" sections of docstrings.
plugins:
- mkdocstrings:
handlers:
matlab:
options:
show_docstring_classes: true
[project.plugins.mkdocstrings.handlers.matlab.options]
show_docstring_classes = true
::: +matlab_namespace
options:
show_docstring_classes: false
Source files
+module
+submodule
Contents.m
subfunction.m
aClass.m
do_something.m
readme.m
Functions:
do_something: Do something.
Classes:
aClass: Summary
Namespaces:
submodule: This is a submodule
% This is a submodulePreview
::: +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
boolTrue
Whether to render the "Namespaces" sections of docstrings.
plugins:
- mkdocstrings:
handlers:
matlab:
options:
show_docstring_namespaces: true
[project.plugins.mkdocstrings.handlers.matlab.options]
show_docstring_namespaces = true
::: +matlab_namespace
options:
show_docstring_namespaces: false
Source files
+module
+submodule
Contents.m
subfunction.m
aClass.m
do_something.m
readme.m
Functions:
do_something: Do something.
Classes:
aClass: Summary
Namespaces:
submodule: This is a submodule
% This is a submodulePreview
::: +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
boolTrue
Whether to render the textual blocks (including admonitions) of docstrings.
plugins:
- mkdocstrings:
handlers:
matlab:
options:
show_docstring_description: true
[project.plugins.mkdocstrings.handlers.matlab.options]
show_docstring_description = true
::: matlab_callable
options:
show_docstring_description: false
Class.m
Preview
show_docstring_examples¤
- Type
boolTrue
Whether to render the "Examples" sections of docstrings.
plugins:
- mkdocstrings:
handlers:
matlab:
options:
show_docstring_examples: true
[project.plugins.mkdocstrings.handlers.matlab.options]
show_docstring_examples = true
::: matlab_callable
options:
show_docstring_examples: false
print_hello.m
Preview
show_docstring_input_arguments¤
- Type
boolTrue
Whether to render the "Parameters" sections of docstrings. The accepted title headings are inputs or input arguments (case-insensitive).
plugins:
- mkdocstrings:
handlers:
matlab:
options:
show_docstring_input_arguments: true
[project.plugins.mkdocstrings.handlers.matlab.options]
show_docstring_input_arguments = true
::: matlab_callable
options:
show_docstring_input_arguments: false
do_something.m
Preview
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
boolTrue
Whether to render the "Name-value pairs" sections of docstrings. The accepted title headings are name-value pairs or name-value arguments (case-insensitive).
plugins:
- mkdocstrings:
handlers:
matlab:
options:
show_docstring_name_value_arguments: true
[project.plugins.mkdocstrings.handlers.matlab.options]
show_docstring_name_value_arguments = true
::: matlab_callable
options:
show_docstring_name_value_arguments: false
do_varargin.m
Preview
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
boolTrue
Whether to render the "Returns" sections of docstrings. The accepted title headings are outputs or output arguments (case-insensitive).
plugins:
- mkdocstrings:
handlers:
matlab:
options:
show_docstring_output_arguments: true
[project.plugins.mkdocstrings.handlers.matlab.options]
show_docstring_output_arguments = true
::: matlab_callable
options:
show_docstring_output_arguments: false
do_output.m
Preview
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).