Skip to main content

Sphinx "matlabdomain" extension

Project description

Github Actions


sphinxcontrib-matlabdomain – Sphinx domain for auto-documenting MATLAB

This extension provides a Sphinx domain for automatically generating doumentation from MATLAB source files. It is modelled after the Python autodoc.

The extension allows you to have your documentation and source files together and use the powerful Sphinx documentation tool. All your MATLAB file help text can be automatically included in the your documentation and output as for instance HTML.

The extension works really well with sphinx.ext.napoleon.

Recent Changes.


The Python package must be installed with:

pip install -U sphinxcontrib-matlabdomain

In general, the usage is the same as for documenting Python code. The package requires Python >= 3.6 and Sphinx >= 4.0.0.

For a Python 2 compatible version the package must be installed with:

pip install sphinxcontrib-matlabdomain==0.11.8


In your Sphinx file add sphinxcontrib.matlab to the list of extensions.

extensions = ['sphinxcontrib.matlab', 'sphinx.ext.autodoc']

Additional Configuration


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.


The encoding of the MATLAB files. By default, the files will be read as utf-8 and parsing errors will be replaced using ? chars.


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:


MATLAB object

.. module:: foldername

folders, packages and namespaces

.. currentmodule:: foldername

  • set folder but do not link

.. automodule:: foldername

  • auto-document


  • reference

.. function:: funcname

function definition and signature

.. autofunction:: funcname()

  • auto-document


  • reference

.. script:: scriptname

script definition

.. autoscript:: scriptname

  • auto-document


  • reference

.. class:: classname()

class definition and optional signature

.. autoclass:: classname

  • auto-document


  • reference

.. method:: methname()

method definition and signature

.. automethod:: methname

  • auto-document


  • reference

.. staticmethod:: statmethname()

static method definition and signature

.. automethod:: statmethname

  • auto-document


  • reference

.. attribute:: attrname

property definition

.. autoattribute:: attrname

  • auto-document


  • reference

.. application:: appname

application definition

.. autoapplication:: appname

  • auto-document


  • reference

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 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.

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
        x % a property

        % Multiple lines before a
        % property can also be used
        function h = MyHandleClass(x)
            h.x = x
        function x = get.x(obj)
        % how is this displayed?
            x = obj.x
    methods (Static)
        function w = my_static_function(z)
        % A static function in :class:`MyHandleClass`.
        % :param z: input z
        % :returns: w

            w = z

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

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:


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:


Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinxcontrib-matlabdomain-0.14.1.tar.gz (89.2 kB view hashes)

Uploaded source

Built Distribution

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page