Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
125 lines (84 loc) · 2.57 KB

CONTRIBUTING.md

File metadata and controls

125 lines (84 loc) · 2.57 KB

Contributing to Sphinx-SimplePDF

Thank you for your interest in contributing to Sphinx-SimplePDF! This document provides guidelines and instructions for contributing.

Getting Started

Prerequisites

  • Python 3.10 or higher
  • uv package manager

Note for macOS users: We recommend using the devcontainer for building and testing, as WeasyPrint has additional system dependencies that are easier to manage in a containerized environment.

Setting Up the Development Environment

  1. Clone the repository:

    git clone https://github.com/useblocks/sphinx-simplepdf.git
cd sphinx-simplepdf

  2. Install dependencies using uv:

    uv sync --group dev

  3. Install pre-commit hooks:

    uv run pre-commit install

Development Workflow

Running Tests

uv run pytest

For parallel test execution:

uv run pytest -n auto

Code Quality

This project uses several tools to maintain code quality:

  • Ruff - Linting and formatting
  • mypy - Static type checking
  • pre-commit - Automated checks before commits

Running Pre-commit Manually

uv run pre-commit run --all-files

Running Individual Checks

# Linting
uv run ruff check .

# Formatting
uv run ruff format .

# Type checking
uv run mypy .

Building Documentation

uv sync --extra docs
cd docs
make html

Building a PDF (Testing the Extension)

cd docs
make simplepdf

The generated PDF will be in docs/_build/simplepdf/.

Submitting Changes

Pull Request Process

  1. Fork the repository and create a new branch from main
  2. Make your changes
  3. Ensure all tests pass and pre-commit checks succeed
  4. Submit a pull request to the main branch

Commit Messages

Write clear and descriptive commit messages that explain what changes were made and why.

Code Style

  • Follow the existing code style in the project
  • Maximum line length is 120 characters
  • Use type hints where appropriate
  • Keep changes focused and avoid unrelated modifications

Reporting Issues

When reporting issues, please include:

  • A clear description of the problem
  • Steps to reproduce the issue
  • Expected vs actual behavior
  • Python version and OS information
  • Any relevant error messages or logs

Questions?

If you have questions, feel free to open an issue on the GitHub repository.

License

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