sphinx-matlab-apidoc

Generate reStructuredText files for MATLAB projects automatically, similar to sphinx-apidoc for Python.

When to Use

  • You want a complete API reference without hand-writing .rst files.

  • Your MATLAB project has many packages/classes and you need consistent docs.

  • You want to regenerate API pages when source code files are added or deleted. Note, regeneration is not needed for changes within existing files. Rebuilding the Sphinx docs will pick up changes automatically.

Quick Start

From your docs directory (assuming MATLAB sources are in ../src):

# Force overwrite (-f), write output to docs/api (-o api), scan ../src
sphinx-matlab-apidoc -f -o api ../src

Where:

  • -f forces overwriting existing files

  • -o api writes generated RST files to the api folder

  • ../src is the path to your MATLAB source files

Then include the generated index in your toctree (e.g. in docs/index.rst):

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   api/index

Re-run the command whenever MATLAB sources are added or deleted to refresh the generated RST.

Common Options

  • -o OUTPUT / --output-dir OUTPUT: Target folder for generated RST (e.g. api)

  • -f / --force: Overwrite existing files

  • -n / --dry-run: Show what would be generated without writing

  • --max-files N: Max files per page (pagination), default 50

Examples

Basic generation (no overwrite):

sphinx-matlab-apidoc -o api ../src

Dry run to inspect changes:

sphinx-matlab-apidoc -n -o api ../src

Increase page size to 100 entries:

sphinx-matlab-apidoc --max-files 100 -o api ../src

Tips and Pitfalls

  • Run from the docs root so relative paths are simple.

  • Avoid folders starting with _ and names with hyphens; they may be skipped because Python-style rules apply internally.

  • MATLAB package and class folders are supported: use +mypackage and @MyClass.

  • After generation, ensure matlab_src_dir in conf.py still points to your MATLAB sources when building Sphinx.

Troubleshooting

  • If pages are missing, verify the source path you passed (e.g. ../src) and rerun with --dry-run to see what would be emitted.

  • If builds warn about missing toctree entries, confirm api/index is listed in your toctree.

  • For large projects, use --max-files to control pagination and keep pages readable.