Quick Reference

Essential commands and workflows for development. Bookmark this page!

Common Commands

Setup

# Clone repository
git clone https://github.com/sphinx-contrib/matlabdomain.git
cd matlabdomain

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate      # Windows

# Install dependencies
pip install -r dev-requirements.txt # For development
pip install -r rtd-requirements.txt # For docs

# Install pre-commit hooks
pre-commit install

Testing

# Run tests
 pytest

 # Verbose output
 pytest -v

 # Stop on first failure
 pytest -x

 # Run specific test file
 pytest tests/test_parse_mfile.py

 # Run specific test
 pytest tests/test_parse_mfile.py::test_function_name

 # Run with coverage (terminal summary with missing lines, branch-aware)
 pytest --cov=sphinxcontrib --cov-report=term-missing --cov-branch

 # Run with coverage (terminal summary, branch-aware)
 pytest --cov=sphinxcontrib --cov-report=term --cov-branch

 # Coverage (HTML report)
 pytest --cov=sphinxcontrib --cov-report=html --cov-branch

 # Run slow integration tests
 pytest -m slow test_slow/

Code Quality

# Run all pre-commit checks
pre-commit run --all-files

# Lint and format
ruff check .
ruff format .

# Type check (if mypy configured)
mypy sphinxcontrib/

Documentation

 # Build HTML docs
 cd docs && make html

 # Clean build
 cd docs && make clean && make html

 # View docs (Linux)
 xdg-open docs/_build/html/index.html

 # View docs (macOS)
 open docs/_build/html/index.html

 # View docs (Windows)
 start docs/_build/html/index.html

# Live preview with sphinx-autobuild
 cd docs && make livehtml

Git Workflow

# Create feature branch
git checkout -b feature/my-feature

# Make changes, then
git add .
git commit -m "feat: add new feature"

# Push to GitHub
git push origin feature/my-feature

Key Files Reference

Source Code

File

Purpose

sphinxcontrib/matlab.py

Main domain implementation, roles, directives

sphinxcontrib/mat_types.py

MATLAB type definitions (Class, Function, etc.)

sphinxcontrib/mat_documenters.py

Autodoc documenters for extracting docs

sphinxcontrib/mat_directives.py

Autodoc directive implementations

sphinxcontrib/mat_tree_sitter_parser.py

AST parser using tree-sitter

sphinxcontrib/mat_lexer.py

Syntax highlighting lexer

Configuration

File

Purpose

pyproject.toml

Project metadata, tool configs (ruff, pytest, etc.)

setup.py

Package installation configuration

pytest.ini

pytest configuration

tox.ini

Testing across multiple Python/Sphinx versions

.pre-commit-config.yaml

Pre-commit hook configuration

docs/conf.py

Sphinx documentation configuration

Dependencies

File

Purpose

dev-requirements.txt

Development dependencies (pytest, ruff, etc.)

rtd-requirements.txt

ReadTheDocs build requirements

setup.py

Package dependencies (install_requires)

Common Workflows

Adding a New Feature

  1. Create branch: git checkout -b feature/my-feature

  2. Write code in sphinxcontrib/

  3. Add tests in tests/test_myfeature.py

  4. Run tests: pytest

  5. Update documentation in docs/

  6. Update CHANGES.rst

  7. Commit: git commit -m "feat: description"

  8. Push and create PR

Fixing a Bug

  1. Create branch: git checkout -b fix/issue-description

  2. Write failing test that reproduces the bug

  3. Fix the bug in sphinxcontrib/

  4. Verify test passes: pytest

  5. Update CHANGES.rst

  6. Commit: git commit -m "fix: description"

  7. Push and create PR

Adding Documentation

  1. Create .rst file in appropriate docs/ subdirectory

  2. Add to toctree in parent page

  3. Write content in reStructuredText

  4. Build: cd docs && make html

  5. Review in browser

  6. Commit and push

Reviewing a PR

  1. Checkout PR branch: git fetch origin && git checkout pr-branch

  2. Install: pip install -e .

  3. Run tests: pytest

  4. Build docs: cd docs && make html

  5. Review code changes

  6. Test manually if needed

  7. Leave feedback on GitHub

Important Configuration Settings

conf.py (Sphinx)

# Essential MATLAB configuration
extensions = ['sphinxcontrib.matlab', 'sphinx.ext.autodoc']
matlab_src_dir = '/path/to/matlab/src'
primary_domain = 'mat'

# Optional enhancements
matlab_short_links = True
matlab_auto_link = 'basic'
matlab_show_property_default_values = True

pyproject.toml

[tool.ruff]
line-length = 88
target-version = "py38"

[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = "test_*.py"

Troubleshooting Quick Fixes

Tests Failing

# Clean and reinstall
pip uninstall sphinxcontrib-matlabdomain
pip install -e .
pytest

Import Errors

# Verify environment
which python
pip list | grep sphinx

# Reinstall in editable mode
pip install -e .

Pre-commit Failing

# Update hooks
pre-commit autoupdate

# Run manually
pre-commit run --all-files

Documentation Not Building

# Clean build
cd docs
make clean
make html

CI Failing on GitHub

  • Check .github/workflows/python-package.yml

  • Run same commands locally

  • Ensure all tests pass locally first

Code Snippets

Testing a MATLAB Function

from sphinxcontrib.mat_types import MatFunction

# Parse a MATLAB file
func = MatFunction.from_file("path/to/function.m")
print(func.name)
print(func.args)
print(func.docstring)

Creating a Test

import pytest
from sphinxcontrib.mat_types import MatClass

def test_class_parsing():
    cls = MatClass.from_file("MyClass.m")
    assert cls.name == "MyClass"
    assert len(cls.methods) > 0

Debugging Sphinx Build

# In conf.py, add logging
import logging
logging.basicConfig(level=logging.DEBUG)

Environment Variables

Useful environment variables:

# Set MATLAB source directory
export MATLAB_SRC_DIR=/path/to/matlab

# Python debugging
export PYTHONVERBOSE=1

# Pytest options
export PYTEST_ADDOPTS="-v --tb=short"

See Also