Contributing

Thank you for your interest in contributing to sphinxcontrib-matlabdomain! This guide will help you get started.

Development Setup

Prerequisites

Python 3.8 or higher
Git
A code editor (VS Code recommended)

Clone the Repository

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

Create Virtual Environment

# Create virtual environment
python -m venv .venv

# Activate it (Linux/macOS)
source .venv/bin/activate

# Activate it (Windows)
.venv\Scripts\activate

Install Dependencies

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

# Install documentation dependencies
pip install -r rtd-requirements.txt

# Install package in editable mode
pip install -e .

Install Pre-commit Hooks

pre-commit install

This ensures code quality checks run before each commit.

Verify Installation

# Run tests
pytest

# Build documentation
cd docs && make html && cd ..

If everything passes, you’re ready to contribute!

Development Workflow

1. Create a Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-description

2. Make Changes

Edit code, add tests, update documentation as needed.

3. Run Tests

# Run all tests
pytest

# Run specific test file
pytest tests/test_parse_mfile.py

# 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

# Run with coverage (HTML report)
pytest --cov=sphinxcontrib --cov-report=html --cov-branch

4. Check Code Quality

# Lint and format (pre-commit does this automatically)
pre-commit run --all-files

5. Commit Changes

git add .
git commit -m "feat: add new feature"

# Or for bug fixes
git commit -m "fix: resolve issue with class parsing"

Commit Message Convention:

feat: - New feature
fix: - Bug fix
docs: - Documentation changes
test: - Test additions/changes
refactor: - Code refactoring
chore: - Maintenance tasks

6. Push and Create Pull Request

git push origin feature/your-feature-name

Then create a pull request on GitHub.

Code Style

We use ruff for code formatting and linting.

Formatting Rules

Indentation: 4 spaces
Line length: 88 characters (Black style)
Quotes: Double quotes preferred
Import sorting: Automatic via ruff

Example:

"""Module docstring."""

import os
from pathlib import Path

from sphinx.util import logging

logger = logging.getLogger(__name__)


class MyClass:
    """Class docstring.

    Args:
        param: Description of parameter.
    """

    def __init__(self, param):
        self.param = param

    def method(self):
        """Method docstring."""
        return self.param * 2

Documentation Style

Docstrings: Google style or NumPy style
Comments: Explain why, not what
Type hints: Use where helpful, but not required

Testing Guidelines

Writing Tests

Create test file: tests/test_yourfeature.py
Use pytest fixtures for setup
Test edge cases and error handling
Aim for high coverage (>80%)

Test Structure:

import pytest
from sphinxcontrib.mat_types import MatFunction


def test_function_parsing():
    """Test basic function parsing."""
    func = MatFunction.from_file("path/to/function.m")
    assert func.name == "function_name"
    assert len(func.args) == 2


def test_function_with_no_args():
    """Test function without arguments."""
    func = MatFunction.from_file("path/to/no_args.m")
    assert func.args == []


def test_invalid_function():
    """Test error handling for invalid function."""
    with pytest.raises(ValueError):
        MatFunction.from_file("invalid.m")

Running Tests

# All tests
pytest

# Specific test file
pytest tests/test_parse_mfile.py

# Specific test function
pytest tests/test_parse_mfile.py::test_function_name

# With verbose output
pytest -v

# 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

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

# Stop on first failure
pytest -x

Test Organization

tests/
├── test_*.py              # Unit tests
├── roots/                 # Integration test configurations
│   └── test-*/
│       ├── conf.py
│       ├── index.rst
│       └── src/           # MATLAB test files
└── helper.py              # Test utilities

Documentation Contributions

Documentation is just as important as code!

Building Documentation

cd docs
make html

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

# View in browser (macOS)
open _build/html/index.html

# View in browser (Windows)
start _build/html/index.html

Adding New Pages

Create .rst file in appropriate directory
Add to toctree in index.rst or parent page
Write content in reStructuredText format
Build and verify

Documentation Structure:

docs/
├── getting-started/       # Tutorials for new users
├── user-guide/            # Feature documentation
├── developer-guide/       # Contributing guides
└── reference/             # API reference

ReStructuredText Tips

Headings:

=======
Title
=======

Section
=======

Subsection
----------

Subsubsection
^^^^^^^^^^^^^

Code blocks:

.. code-block:: python

   def hello():
       print("Hello!")

Links:

:doc:`page-name`
:ref:`section-label`
`External link <https://example.com>`_

Pull Request Guidelines

Before Submitting

✅ Checklist:

[ ] Tests pass (pytest)
[ ] Code is formatted (pre-commit run --all-files)
[ ] Documentation is updated
[ ] CHANGES.rst is updated (for features/fixes)
[ ] Commit messages follow convention

PR Description

Include:

What: Brief description of changes
Why: Motivation and context
How: Implementation approach
Testing: How you tested the changes
Screenshots: For UI changes (if applicable)

Template:

## Description
Brief summary of changes

## Motivation
Why this change is needed

## Changes
- Added X
- Fixed Y
- Updated Z

## Testing
How to verify the changes work

## Checklist
- [x] Tests pass
- [x] Documentation updated
- [x] CHANGES.rst updated

Review Process

Automated checks run (GitHub Actions)
Maintainer reviews code
Feedback and discussion
Approval and merge

Reporting Issues

Found a Bug?

Create an issue with:

Title: Clear, descriptive
Description: What happened vs. what you expected
Reproduction: Minimal example to reproduce
Environment: Python version, Sphinx version, OS
Error messages: Full error output