Sphinx "matlabdomain" extension
Project description
sphinxcontrib-matlabdomain – Sphinx domain for auto-documenting MATLAB
This Sphinx contrib extension provides a Sphinx domain for auto-documenting MATLAB source files, in similar manner as sphinx.ext.autodoc. It works really well with sphinx.ext.napoleon.
Recent Changes.
Usage
The Python package must be installed with:
pip install -U sphinxcontrib-matlabdomain
In general, the usage is the same as for documenting Python code.
Configuration
In your Sphinx conf.py file add sphinxcontrib.matlab to the list of extensions.
extensions = ['sphinxcontrib.matlab', 'sphinx.ext.autodoc']
Additional Configuration
- matlab_src_dir
- In order for the Sphinx MATLAB domain to auto-document MATLAB source code, set the config value of matlab_src_dir to the absolute path. Currently only one MATLAB path can be specified, but all subfolders in that tree will be searched.
- matlab_src_encoding
- The encoding of the MATLAB files. By default, the files will be read as utf-8 and parsing errors will be replaced using ? chars.
- matlab_keep_package_prefix
- Determines if the MATLAB package prefix + is displayed in the generated documentation. Default is true. When false, packages are still referred to in ReST using +pakage.+subpkg.func but the output will be pakage.other.func().
For convenience the primary domain can be set to mat.
Roles and Directives
Please see Sphinx Domains and sphinx.ext.autodoc for documentation on the use of roles and directives. MATLAB code can be documented using the following roles and directives:
Directive | MATLAB object |
---|---|
.. module:: foldername | folders, packages and namespaces |
.. currentmodule:: foldername |
|
.. automodule:: foldername |
|
:mod:`foldername` |
|
.. function:: funcname | function definition and signature |
.. autofunction:: funcname() |
|
:func:`funcname` |
|
.. script:: scriptname | script definition |
.. autoscript:: scriptname |
|
:scpt:`scriptname` |
|
.. class:: classname() | class definition and optional signature |
.. autoclass:: classname |
|
:class:`classname` |
|
.. method:: methname() | method definition and signature |
.. automethod:: methname |
|
:meth:`methname` |
|
.. staticmethod:: statmethname() | static method definition and signature |
.. automethod:: statmethname |
|
:meth:`methname` |
|
.. attribute:: attrname | property definition |
.. autoattribute:: attrname |
|
:attr:`attrname` |
|
.. application:: appname | application definition |
.. autoapplication:: appname |
|
:app:`appname` |
|
Several options are available for auto-directives.
- :members: auto-document public members
- :show-inheritance: list bases
- :undoc-members: document members without docstrings
- :annotation: specifies attribute annotation instead of default
There are also several config values that can be set in conf.py that will affect auto-docementation.
- autoclass_content can be set to class, both or init, which determines which docstring is used for classes. The constructor docstring is used when this is set to init.
- autodoc_member_order can be set to alphabetical, groupwise or bysource.
- autodoc_default_flags can be set to a list of options to apply. Use the no-flag directive option to disable this config value once.
Note
The module roles and directives create a psuedo namespace for MATLAB objects, similar to a package. They represent the path to the folder containing the MATLAB object. If no module is specified then Sphinx will assume that the object is a built-in.
Example: given the following MATLAB source in folder test_data:
classdef MyHandleClass < handle & my.super.Class % a handle class % % :param x: a variable %% some comments properties x % a property end methods function h = MyHandleClass(x) h.x = x end function x = get.x(obj) % how is this displayed? x = obj.x end end methods (Static) function w = my_static_function(z) % A static function in :class:`MyHandleClass`. % % :param z: input z % :returns: w w = z end end end
Use the following to document:
Test Data ========= This is the test data module. .. automodule:: test_data :mod:`test_data` is a really cool module. My Handle Class --------------- This is the handle class definition. .. autoclass:: MyHandleClass :show-inheritance: :members:
Module Index
Since version 0.10.0 the MATLAB Module Index should be linked to with:
`MATLAB Module Index <mat-modindex.html>`_
Older versions, used the Python Module Index, which was linked to with:
:ref:`modindex`
Documenting Python and MATLAB sources together
Since version 0.10.0 MATLAB and Python sources can be (auto-)documented in the same Sphinx documentation. For this to work, do not set the primary domain.
Instead use the mat: prefix before the desired directives:
.. automodule:: func .. autofunction:: func.main .. mat:automodule:: matsrc .. mat:autofunction:: matsrc.func
Online Demo
The test docs in the repository are online here: http://bwanamarko.alwaysdata.net/matlabdomain/
Note
Sphinx style markup are used to document parameters, types, returns and exceptions. There must be a blank comment line before and after the parameter descriptions. Currently property docstrings are only collected if they are on the same line following the property definition. Getter and setter methods are documented like methods currently, but the dot is replaced by an underscore. Default values for properties are represented as unicode strings, therefore strings will be double quoted.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Filename, size | File type | Python version | Upload date | Hashes |
---|---|---|---|---|
Filename, size sphinxcontrib_matlabdomain-0.11.7-py3-none-any.whl (39.2 kB) | File type Wheel | Python version py3 | Upload date | Hashes View |
Filename, size sphinxcontrib-matlabdomain-0.11.7.tar.gz (79.6 kB) | File type Source | Python version None | Upload date | Hashes View |
Hashes for sphinxcontrib_matlabdomain-0.11.7-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | aead39c4d1d888041619365725c224d33593567855bfb4ffb1008d97f908851c |
|
MD5 | 57c8bc306d814832f2f66ab10d90027c |
|
BLAKE2-256 | 621670326b20f3029867000a9d7a133407102efe5fa4adfac25b0eb23695277c |
Hashes for sphinxcontrib-matlabdomain-0.11.7.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 305fd2767a770cceb4d8afbc605537383eb54bbc7a3c263bcfed8c72b417b1b3 |
|
MD5 | d8994e757f4ad23c914da27597a86d3e |
|
BLAKE2-256 | cbd2712de866478b74c50c527f0e042d7e29901d3f7de9e2b3122da310c19acd |