Quick Start

Get started with sphinxcontrib-matlabdomain in 5 minutes! This guide assumes you have already installed the extension.

What You’ll Build

In this tutorial, you’ll:

  1. Create a minimal Sphinx project

  2. Configure it to document MATLAB code

  3. Add some MATLAB source files

  4. Generate HTML documentation

Step 1: Create a Sphinx Project

If you don’t have a Sphinx project yet, create one:

# Create a docs directory
mkdir docs
cd docs

# Run Sphinx quickstart
sphinx-quickstart

Answer the prompts:

  • Separate source and build directories? No (just press Enter)

  • Project name: My MATLAB Project

  • Author name: Your Name

  • Project release: 1.0

  • Project language: en (or your language)

This creates a basic Sphinx structure:

docs/
├── conf.py          # Configuration file
├── index.rst        # Main page
├── Makefile         # Build commands (Linux/Mac)
└── make.bat         # Build commands (Windows)

Step 2: Configure for MATLAB

Open conf.py and add sphinxcontrib.matlab to your extensions:

# Add these lines to conf.py
import os

extensions = [
    'sphinx.ext.autodoc',
    'sphinxcontrib.matlab',
    'sphinx.ext.napoleon',  # Optional: for Google/NumPy style docstrings
]

# Point to your MATLAB source directory
matlab_src_dir = os.path.abspath('../src')

# (Optional) Make MATLAB the primary domain
primary_domain = 'mat'

Step 3: Add MATLAB Source Files

Create a src directory next to docs and add a MATLAB file:

# From your project root
mkdir src
cd src

Create a file src/hello.m:

function greeting = hello(name)
% HELLO Say hello to someone
%
% Args:
%     name (char): The name of the person to greet
%
% Returns:
%     char: A greeting message

greeting = ['Hello, ' name '!'];
end

Step 4: Document Your Code

Edit docs/index.rst to include your MATLAB documentation:

Welcome to My MATLAB Project
=============================

.. autofunction:: hello

Step 5: Build the Documentation

Now build your HTML documentation:

# On Linux/macOS
cd docs
make html

# On Windows
cd docs
make.bat html

Open the generated documentation:

# On Linux
xdg-open _build/html/index.html # This likely works too: open _build/html/index.html

# On macOS
open _build/html/index.html

# On Windows
start _build/html/index.html # or call it directly: _build/html/index.html

You should see your documentation with the hello function documented! As shown below:

hello(name)

HELLO Say hello to someone

Parameters:

name (char) – The name of the person to greet

Returns:

A greeting message

Return type:

char

What Just Happened?

  1. Sphinx quickstart created a basic documentation project

  2. conf.py was configured to find your MATLAB source files

  3. autofunction directive automatically extracted documentation from your MATLAB code

  4. make html built your documentation into HTML

Next Steps

Now that you have a working setup, explore more features:

Common Next Questions

How do I document a class?

Use the autoclass directive:

.. autoclass:: MyClass
   :members:

How do I document an entire package?

Use the automodule directive:

.. automodule:: mypackage
   :members:

How do I customize the output?

See Configuration for all available options like:

  • matlab_short_links - Use shorter names

  • matlab_auto_link - Automatically create cross-references

  • matlab_keep_package_prefix - Control package name display

Where do I go for help?