Contributing¶

Thank you for your interest in contributing to typsphinx!

This guide will help you get started with development.

Development Setup¶

Prerequisites¶

Python 3.9 or later
uv (recommended) or pip
Git

Clone and Install¶

# Clone the repository
git clone https://github.com/YuSabo90002/typsphinx.git
cd typsphinx

# Install with development dependencies
uv sync --extra dev

# Or with pip
pip install -e ".[dev]"

Running Tests¶

We use pytest for testing:

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov

# Run specific test file
uv run pytest tests/test_builder.py

# Run with verbose output
uv run pytest -v

Test Coverage¶

We maintain 90%+ test coverage. When adding new features:

Write tests first (TDD approach)
Ensure all tests pass
Check coverage doesn’t decrease

Code Quality¶

We use multiple tools to ensure code quality:

Black (Code Formatting)¶

# Format all code
uv run black .

# Check without modifying
uv run black --check .

Ruff (Linting)¶

# Lint all code
uv run ruff check .

# Auto-fix issues
uv run ruff check --fix .

Mypy (Type Checking)¶

# Type check
uv run mypy typsphinx/

All Checks¶

Run all quality checks:

uv run black .
uv run ruff check .
uv run mypy typsphinx/
uv run pytest --cov

Using Tox¶

We use tox for running tests across multiple Python versions and environments. Tox provides the same commands used in CI, making it easy to reproduce issues locally:

# Run all tox environments (tests, lint, type check, docs)
uv run tox

# Run specific environments
uv run tox -e lint          # Black + Ruff
uv run tox -e type          # Mypy type checking
uv run tox -e py311         # Tests on Python 3.11
uv run tox -e docs-html     # Build HTML documentation
uv run tox -e docs-pdf      # Build PDF documentation
uv run tox -e docs          # Build both HTML and PDF

# Run tests on specific Python versions
uv run tox -e py39,py310,py311,py312

The tox configuration is defined in tox.ini and provides:

Consistent test execution across local and CI environments
Isolated virtual environments for each test run
Same commands work locally and in GitHub Actions

Development Workflow¶

1. Create a Feature Branch¶

git checkout -b feature/your-feature-name

2. Make Changes¶

Write code following the project style
Add tests for new functionality
Update documentation as needed

3. Run Tests and Checks¶

uv run pytest --cov
uv run black .
uv run ruff check .
uv run mypy typsphinx/

4. Commit Changes¶

Use conventional commit messages:

git commit -m "feat: add new feature"
git commit -m "fix: resolve bug in translator"
git commit -m "docs: update configuration guide"

Commit types:

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting)
refactor: Code refactoring
test: Adding tests
chore: Maintenance tasks

5. Push and Create Pull Request¶

git push origin feature/your-feature-name

Then create a pull request on GitHub.

Coding Guidelines¶

Style¶

Follow PEP 8 (enforced by Black and Ruff)
Line length: 88 characters (Black default)
Use type hints for public APIs
Write docstrings for public functions/classes

Documentation¶

Use Google-style docstrings:

def convert_node(node: nodes.Node) -> str:
    """Convert a docutils node to Typst markup.

    Args:
        node: The docutils node to convert

    Returns:
        Typst markup string

    Raises:
        ValueError: If node type is unsupported

    Example:
        >>> node = nodes.paragraph()
        >>> convert_node(node)
        '#par[...]'
    """
    pass

Architecture¶

Builder: Manages build process, file I/O
Writer: Orchestrates document conversion
Translator: Converts individual node types (Visitor pattern)
TemplateEngine: Handles template processing

Testing¶

Write unit tests for individual functions
Write integration tests for complete builds
Use fixtures for test data
Test edge cases and error conditions

Project Structure¶

typsphinx/
├── typsphinx/              # Main package
│   ├── __init__.py         # Extension entry point
│   ├── builder.py          # TypstBuilder
│   ├── pdf.py              # TypstPDFBuilder
│   ├── writer.py           # TypstWriter
│   ├── translator.py       # TypstTranslator
│   ├── template_engine.py  # Template processing
│   └── templates/          # Default templates
├── tests/                  # Test suite
├── docs/                   # Documentation
├── examples/               # Example projects
└── pyproject.toml          # Project configuration

Reporting Issues¶

When reporting bugs:

Check if the issue already exists
Provide a minimal reproducible example
Include your environment details:
- Python version
- Sphinx version
- typsphinx version
- Operating system
Describe expected vs actual behavior

Use our issue templates on GitHub.

Feature Requests¶

For feature requests:

Describe the use case
Explain why it’s needed
Suggest implementation approach (optional)
Consider creating an OpenSpec proposal for major features

Community¶

GitHub: https://github.com/YuSabo90002/typsphinx
Issues: https://github.com/YuSabo90002/typsphinx/issues
Discussions: Use GitHub Discussions for questions

Code of Conduct¶

We follow the Contributor Covenant Code of Conduct:

Be respectful and inclusive
Welcome newcomers
Focus on constructive feedback
Respect differing viewpoints

License¶

By contributing, you agree that your contributions will be licensed under the MIT License.

Thank you for contributing to typsphinx!