Architecture

This guide explains the internal architecture of sphinxcontrib-matlabdomain for developers who want to contribute or understand how it works.

Project Overview

sphinxcontrib-matlabdomain is a Sphinx domain extension that enables automatic documentation generation from MATLAB source code, similar to Sphinx’s Python autodoc extension.

Key Features:

Auto-document MATLAB classes, functions, properties, and methods from source files
Integration with Sphinx documentation framework
Support for MATLAB-specific syntax and conventions
Compatible with Napoleon for Google/NumPy docstring formats
Works with both .m files and .mlapp application files

Project Stats:

Language: Python 3.8+
Main Dependencies: Sphinx (4.0+), tree-sitter (MATLAB parser)
Package: sphinxcontrib-matlabdomain
Repository: https://github.com/sphinx-contrib/matlabdomain

Core Components

The extension consists of six main Python modules:

matlab.py - Main Domain (958 lines)

Purpose: Entry point that registers the MATLAB domain with Sphinx.

Key Responsibilities:

Defines roles (:class:, :func:, :meth:, :prop:)
Registers directives (.. automodule::, .. autoclass::, etc.)
Manages cross-references and linking
Handles domain setup and reference resolution

Main Classes:

MatObject - Base class for all MATLAB object descriptions
MatDomain - The MATLAB domain itself
Various directive classes for manual documentation

mat_types.py - Type System

Purpose: Represents MATLAB code elements as Python objects.

Classes:

MatObject - Base class for all MATLAB entities
MatModule - Represents a package or folder of MATLAB code
MatClass - MATLAB class (handles attributes, inheritance)
MatFunction - Function file (.m file)
MatMethod - Class method
MatProperty - Class property
MatScript - MATLAB script file
MatApplication - MATLAB app (.mlapp file)
MatEnumeration - MATLAB enumeration class
MatModuleAnalyzer - Scans filesystem for MATLAB code
MatException - Exception class

Key Features:

Parses docstrings into description/parameters/returns/examples
Handles MATLAB-specific attributes (class properties, methods)
Manages hierarchical relationships (package/class/method)
File system scanning and module discovery

mat_tree_sitter_parser.py - AST Parser

Purpose: Uses tree-sitter to parse MATLAB syntax trees.

Classes:

MatClassParser - Parses class definitions
MatFunctionParser - Parses function definitions
MatScriptParser - Parses script files

Features:

Extracts function signatures and arguments
Identifies class methods and properties
Parses docstrings and comments
Handles MATLAB syntax specifics (e.g., ellipsis continuation)
Provides fast, accurate parsing using tree-sitter

mat_documenters.py - Documenter Classes

Purpose: Sphinx autodoc-style documenters that extract documentation from MATLAB files.

Classes:

MatlabDocumenter - Base class
ModuleDocumenter - Handles MATLAB packages/modules
ClassDocumenter - Documents MATLAB classes
FunctionDocumenter - Documents functions
PropertyDocumenter - Documents class properties
MethodDocumenter - Documents methods
ApplicationDocumenter - Documents MATLAB apps
EnumerationDocumenter - Documents enumerations

Each documenter:

Finds MATLAB source files
Parses them using mat_tree_sitter_parser
Generates reStructuredText documentation
Handles cross-references to other entities

mat_directives.py - Autodoc Directives

Purpose: Extends Sphinx’s autodoc directive system.

Provides These Directives:

.. automodule:: - Auto-document MATLAB packages
.. autoclass:: - Auto-document MATLAB classes
.. autofunction:: - Auto-document functions
.. autoproperty:: - Auto-document properties
.. automethod:: - Auto-document methods
.. autoenum:: - Auto-document enumerations
.. autoapp:: - Auto-document MATLAB apps

mat_lexer.py - Syntax Highlighting

Purpose: Provides MATLAB code syntax highlighting for Sphinx HTML output.

Features:

Tokenizes MATLAB code
Maps MATLAB syntax to Pygments tokens
Used by .. code-block:: matlab in documentation

Data Flow

Understanding how documentation is generated:

1. User Setup

User configures conf.py:

extensions = ['sphinxcontrib.matlab']
matlab_src_dir = '/path/to/matlab/src'

2. Sphinx Build Starts

Sphinx reads configuration
Loads extensions including sphinxcontrib.matlab
matlab.py registers the domain, roles, and directives

3. Module Discovery

When matlab_src_dir is set:

MatModuleAnalyzer scans the directory tree
Finds all .m and .mlapp files
Builds a map of available modules, classes, and functions

4. Directive Processing

When Sphinx encounters .. autofunction:: myfunction:

The appropriate documenter (e.g., FunctionDocumenter) is invoked
Documenter locates the source file in matlab_src_dir
File is read and passed to parser

5. Parsing

mat_tree_sitter_parser.py processes the source:

Creates an Abstract Syntax Tree (AST)
Extracts function signature, parameters, return values
Extracts docstring comments
Identifies code structure

6. Type Creation

Parser output creates MatType objects:

MatFunction with signature and docstring
Properties filled: name, args, returns, description
Relationships established (e.g., method → class)

7. Documentation Generation

Documenter generates reStructuredText:

Formats function signature
Converts docstring to reST
Adds cross-references for known entities
Returns formatted documentation

8. Cross-Reference Resolution

MatDomain resolves references like :func:`myfunction`:

Looks up entity in domain’s inventory
Creates clickable links in HTML output
Handles short names if matlab_short_links = True

9. HTML Generation

Sphinx converts reST to HTML
mat_lexer.py provides syntax highlighting for code blocks
Final HTML documentation is generated

File System Organization

Source Code Layout

sphinxcontrib/
├── __init__.py                    # Package initialization
├── matlab.py                      # Domain, roles, directives
├── mat_types.py                   # Type system
├── mat_tree_sitter_parser.py      # AST parsing
├── mat_documenters.py             # Autodoc documenters
├── mat_directives.py              # Autodoc directives
├── mat_lexer.py                   # Syntax highlighting
└── sphinx_matlab_apidoc.py        # CLI tool

Test Organization

tests/
├── test_*.py                      # Test modules
├── roots/                         # Sphinx test configurations
│   └── test-*/                    # Each test has its own root
│       ├── conf.py
│       ├── index.rst
│       └── test_data/             # MATLAB test files
└── helper.py                      # Test utilities

Key Algorithms

Module Discovery

MatModuleAnalyzer.find_modules():

Walk directory tree starting from matlab_src_dir
Identify MATLAB packages (+ directories)
Find class folders (@ directories)
Catalog all .m and .mlapp files
Build hierarchical module structure

Name Resolution

When resolving matlab_short_links:

User references :class:`MyClass`
System searches for matching classes
If multiple matches, uses context to disambiguate
Returns full path or shortest unique path
Creates cross-reference in output

Docstring Parsing

From MATLAB comments to structured documentation:

Extract comment block above function/class
Identify sections (Args, Returns, Example, See also)
Parse parameter descriptions
Convert to docutils node tree
Apply Napoleon transformations if enabled

Design Patterns

The Documenter Pattern

Each MATLAB entity type has a corresponding documenter:

class FunctionDocumenter(MatlabDocumenter):
    objtype = 'function'

    def parse_definition(self):
        # Extract function signature
        pass

    def generate(self):
        # Generate documentation
        pass

This follows Sphinx’s autodoc pattern, making it familiar to Sphinx developers.

The Type System

MATLAB entities are represented as Python objects inheriting from MatObject:

class MatFunction(MatObject):
    def __init__(self, name, path, docstring):
        self.name = name
        self.path = path
        self.docstring = docstring
        self.args = []
        self.returns = []

This provides a clean abstraction over MATLAB’s diverse code structures.

Extension Points

For developers extending this project:

Adding New Directive Types

Create a new class in mat_directives.py
Inherit from ObjectDescription
Implement handle_signature() and transform_content()
Register in setup() function

Adding New MatTypes

Create class in mat_types.py inheriting from MatObject
Implement parsing logic
Create corresponding documenter in mat_documenters.py
Add handling to mat_tree_sitter_parser.py

Custom Parsing

To handle new MATLAB syntax:

Update tree-sitter grammar (external dependency)
Modify parser in mat_tree_sitter_parser.py
Extract new information into MatType objects

Dependencies

Core Dependencies

Sphinx (≥4.0.0) - Documentation framework
tree-sitter (≥0.21.3, <0.23.0) - Parser infrastructure
tree-sitter-matlab (≥1.0.2, <1.0.5) - MATLAB grammar
docutils - Document utilities (via Sphinx)

Development Dependencies

pytest - Testing framework
pytest-cov - Coverage reporting
ruff - Linting and formatting
pre-commit - Git hooks
tox - Testing across multiple environments

Architecture

Project Overview

Core Components

matlab.py - Main Domain (958 lines)

mat_types.py - Type System

mat_tree_sitter_parser.py - AST Parser

mat_documenters.py - Documenter Classes

mat_directives.py - Autodoc Directives

mat_lexer.py - Syntax Highlighting

Data Flow

1. User Setup

2. Sphinx Build Starts

3. Module Discovery

4. Directive Processing

5. Parsing

6. Type Creation

7. Documentation Generation

8. Cross-Reference Resolution

9. HTML Generation

File System Organization

Source Code Layout

Test Organization

Key Algorithms

Module Discovery

Name Resolution

Docstring Parsing

Design Patterns

The Documenter Pattern

The Type System

Extension Points

Adding New Directive Types

Adding New MatTypes

Custom Parsing

Dependencies

Core Dependencies

Development Dependencies

See Also