Configuration

This page documents all configuration options for sphinxcontrib-matlabdomain.

Essential Configuration

These settings are required for basic functionality.

extensions

Add the MATLAB domain to your Sphinx extensions:

extensions = [
    'sphinx.ext.autodoc',
    'sphinxcontrib.matlab',
    'sphinx.ext.napoleon',  # Optional but recommended
]

matlab_src_dir

Required. Specify the path to your MATLAB source code:

import os

# Absolute path
matlab_src_dir = '/absolute/path/to/matlab/src'

# Relative path (recommended)
this_dir = os.path.dirname(os.path.abspath(__file__))
matlab_src_dir = os.path.abspath(os.path.join(this_dir, '..', 'src'))

The extension searches this directory and all subdirectories for .m files.

Note

Currently only one MATLAB path can be specified, but all subfolders in that tree will be searched.

Optional Configuration

primary_domain

Make MATLAB the primary domain for convenience:

primary_domain = 'mat'

This allows you to write:

.. autofunction:: myfunction

Instead of:

.. mat:autofunction:: myfunction

Default: 'py' (Python)

matlab_keep_package_prefix

Control whether package prefixes (+) are displayed:

matlab_keep_package_prefix = True

Effect:

  • True: Display as +mypackage.MyClass

  • False: Display as mypackage.MyClass

Default: True

Note

This is automatically set to False when matlab_short_links = True.

matlab_show_property_default_values

Show default values for class properties:

matlab_show_property_default_values = True

Effect:

Shows property initialization values in class documentation.

Default: False

Added in: Version 0.17.0

Example Complete Configuration

Here’s a complete conf.py with common settings:

# Configuration file for the Sphinx documentation builder.
import os

# -- Project information -----------------------------------------------------
project = 'MyMatlabProject'
copyright = '2025, Your Name'
author = 'Your Name'
release = '1.0.0'

# -- General configuration ---------------------------------------------------
extensions = [
    'sphinx.ext.autodoc',
    'sphinxcontrib.matlab',
    'sphinx.ext.napoleon',
    'sphinx.ext.viewcode',      # Add links to source code
    'sphinx.ext.intersphinx',   # Link to other projects
]

# MATLAB Configuration
this_dir = os.path.dirname(os.path.abspath(__file__))
matlab_src_dir = os.path.abspath(os.path.join(this_dir, '..', 'src'))
primary_domain = 'mat'
matlab_short_links = True
matlab_auto_link = 'basic'
matlab_show_property_default_values = True

# Build configuration
templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

# -- Options for HTML output -------------------------------------------------
html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']
html_logo = '_static/logo.png'  # Optional

# Theme options
html_theme_options = {
    'navigation_depth': 4,
    'collapse_navigation': False,
}

Configuration for Different Project Structures

Single Directory

If all your MATLAB files are in one directory:

matlab_src_dir = os.path.abspath(os.path.join(this_dir, '..', 'matlab'))

Multiple Levels with Packages

If you have packages and classes in subdirectories:

src/
├── utilities.m
├── +mypackage/
│   ├── helper.m
│   └── +subpackage/
│       └── tool.m
└── @MyClass/
    └── MyClass.m

matlab_src_dir = os.path.abspath(os.path.join(this_dir, '..', 'src'))
matlab_short_links = True

Important

Folder Naming Rules

sphinxcontrib-matlabdomain uses Python import mechanisms internally, so it follows Python package naming conventions:

  • Avoid folders starting with _ (underscore) - they may be treated as private and excluded

  • Do not use - (hyphen) in folder names - use _ (underscore) instead

  • Folder names must be valid Python identifiers

MATLAB-specific prefixes are fine:

  • +mypackage/ for MATLAB packages

  • @MyClass/ for MATLAB class folders

Examples of problematic folder names:

  • _internal/ - starts with underscore (may be ignored)

  • my-utils/ - contains hyphen (won’t work)

  • 2dtools/ - starts with number (invalid Python identifier)

Better alternatives:

  • internal/ or internals/

  • my_utils/

  • tools2d/ or two_d_tools/

Documentation Next to Source

If your docs are in the same directory as source:

project/
├── docs/
│   └── conf.py
└── src/
    └── *.m

matlab_src_dir = os.path.abspath(os.path.join(this_dir, '..', 'src'))

Separate Docs Project

If documentation is in a completely separate repository:

# Use absolute path
matlab_src_dir = '/path/to/matlab/project/src'

# Or use environment variable
import os
matlab_src_dir = os.environ.get('MATLAB_SRC_DIR', '/default/path')

Advanced Configuration

Napoleon Extension

Enable Google or NumPy style docstrings:

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

# Napoleon settings
napoleon_google_docstring = True
napoleon_numpy_docstring = True
napoleon_include_init_with_doc = True
napoleon_use_param = True
napoleon_use_rtype = True

Custom CSS

Add custom styling:

html_static_path = ['_static']
html_css_files = ['custom.css']

Create _static/custom.css for your styles.

Intersphinx Linking

Link to other project documentation:

extensions = [
    # ... other extensions
    'sphinx.ext.intersphinx',
]

intersphinx_mapping = {
    'python': ('https://docs.python.org/3', None),
    'numpy': ('https://numpy.org/doc/stable/', None),
}

Troubleshooting Configuration

Configuration Not Working

  1. Restart the build - Run make clean && make html

  2. Check syntax - Python is whitespace-sensitive

  3. Verify paths - Use print(matlab_src_dir) to debug

  4. Check imports - Make sure all extensions are installed

matlab_src_dir Not Found

Add debug output to conf.py:

import os
this_dir = os.path.dirname(os.path.abspath(__file__))
matlab_src_dir = os.path.abspath(os.path.join(this_dir, '..', 'src'))

print(f"Looking for MATLAB sources in: {matlab_src_dir}")
print(f"Directory exists: {os.path.exists(matlab_src_dir)}")

Run the build to see the output.

Extension Not Loaded

Check if sphinxcontrib-matlabdomain is installed:

pip show sphinxcontrib-matlabdomain
python -c "import sphinxcontrib.matlab; print('OK')"

See Also