CONTRIBUTING.md

Contributing to sphinx-needs-tree-map

Thank you for your interest in contributing to sphinx-needs-tree-map!

Development Setup

1. Clone the repository:

   git clone https://github.com/patdhlk/sphinx-needs-tree-map.git
   cd sphinx-needs-tree-map

2. Create a virtual environment and install dependencies:

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   pip install -e ".[dev,docs]"

3. Install pre-commit hooks:

   pip install pre-commit
   pre-commit install

Running Tests

pytest tests/ -v

With coverage:

pytest tests/ -v --cov=sphinx_needs_tree_map --cov-report=html

Code Style

This project uses:

• ruff for linting and formatting
• mypy for type checking

Run checks manually:

ruff check sphinx_needs_tree_map tests
ruff format sphinx_needs_tree_map tests
mypy sphinx_needs_tree_map

Or use pre-commit:

pre-commit run --all-files

Building Documentation

cd docs
make html
# Open _build/html/index.html

Submitting Changes

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes and add tests
4. Ensure all tests pass and code style checks pass
5. Commit with a clear message
6. Push to your fork and create a Pull Request

Pull Request Guidelines

• Include tests for new functionality
• Update documentation as needed
• Follow the existing code style
• Keep commits focused and atomic
• Reference any related issues

Reporting Issues

• Use the GitHub issue templates
• Include Sphinx and sphinx-needs versions
• Provide a minimal reproducible example when possible

License

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