Usage¤
Installation¤
You can install this handler by specifying it as a dependency:
# 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
:
plugins:
- mkdocstrings:
default_handler: matlab
matlab:
... # the MATLAB handler configuration
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
Namespaces¤
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
Folders¤
Similarly to namepaces, all contents of a folder can be fully documented by specifying the relative path of a folder with respect to the mkdocs.yml
config file. E.g. the following repository
📁 src
└── 📁 module
├── 📄 myfunction.m
├── 📄 myClass.m
├── 📁 submodule
│ └── 📄 myfunction.m
└── 📁 +mynamespace
└── 📄 namespacefunction.m
📁 docs
└── 📄 index.md
📄 mkdocs.yml
is documented with:
::: src/module
In the case above the function module/submodule/myfunction.m
overshadows the function module/myfunction.m
on the MATLAB path. This means that in the global namespace myfunction will always call module/submodule/myfunction.m
, which is the function to be documented by ::: myfunction
.
While this kind of behavior is strictly recommended against, mkdocstrings-matlab does support documenting the shadowed function by using its path. The file extension is now stricty required.
::: src/module/myfunction.m
Tip
A folder identifier must strictly contain the /
character. For a folder foo
that is in the same directory with mkdocs.yml
, use ::: ./foo
.
Tip
If the mkdocs.yml
lives inside of a subdirectly that does not contain source code, use relative paths e.g. ../src/module
.
Tip
Sub-selecting folder members are possible with the members options.
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:
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:
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:
plugins:
- mkdocstrings:
handlers:
matlab:
options:
do_something: true
...and locally, overriding the global configuration:
::: 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