Troubleshooting

Common issues and their solutions.

Installation Issues

Package Not Found

Symptom: pip install sphinxcontrib-matlabdomain fails

Solution:

pip install --upgrade pip
pip install sphinxcontrib-matlabdomain

Configuration Issues

matlab_src_dir Not Found

Symptom: Warning: “matlab_src_dir not set” or “directory not found”

Solution: Check your 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'))

# Debug: print the path
print(f"Looking for MATLAB sources in: {matlab_src_dir}")

Extension Not Loading

Symptom: Extension not recognized

Solution: Verify installation:

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

Build Issues

Functions Not Appearing

Symptom: autofunction directive produces no output

Possible causes:

File not in matlab_src_dir
Typo in function name (case-sensitive)
Need to rebuild: make clean && make html

Classes Not Showing Members

Symptom: Class documented but no methods/properties shown

Solution: Add :members: option:

.. autoclass:: MyClass
   :members:
   :undoc-members:

Build Warnings

Symptom: Warnings during build

Solutions:

Read the warning message carefully
Check file paths and names
Verify MATLAB syntax is valid
Run make clean && make html

Folders Starting with Underscore Not Found

Symptom: MATLAB files in folders starting with _ are not being documented

Cause: Sphinx follows Python package naming conventions where folders starting with _ are typically treated as private/internal and may be excluded by default.

Solutions:

Rename folders to not start with underscore (recommended):

Before: src/_internal/myfile.m
After:  src/internal/myfile.m

Update exclude_patterns in conf.py if the folder is being excluded:

# Default excludes _build, etc.
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

Python Package Naming Rules

Important: sphinxcontrib-matlabdomain uses Python import mechanisms internally, which means it follows Python naming conventions:

Folders starting with _ may be treated as private
Folders with - (hyphen) won’t work - use _ (underscore) instead for multi-word names
Module names must be valid Python identifiers

Best practices:

Use alphanumeric folder names: utils, helpers, core
For MATLAB packages, use the + prefix: +mypackage
For MATLAB class folders, use the @ prefix: @MyClass
Avoid special characters in folder/file names except + and @
Don’t use a number or symbol as the first character of a folder name

What’ll notice here is these rules are very similar to MATLAB’s own naming conventions for packages, classes, and variables. When you deviate, it may work but can lead to unexpected and hard to debug issues.

Example structure that works well:

src/
├── utilities.m           # Simple function
├── +mypackage/           # MATLAB package (note the +)
│   ├── helper.m
│   └── validator.m
├── @MyClass/             # MATLAB class folder (note the @)
│   └── MyClass.m
└── submodule/            # Regular folder (no underscore prefix)
    └── tools.m

Getting Help

If you’re still stuck:

Check Configuration for correct settings
Search GitHub Issues
Create a new issue with:
- Your conf.py
- Example MATLAB file
- Full error message
- Python/Sphinx versions