4. Contributing

We welcome contributions! To ensure a smooth process, please follow these guidelines.

4.1. Code Quality and Styling

We use automated tools to ensure code quality and consistent styling. To make following these standards as painless as possible, we use Ruff for linting and formatting.

Before submitting a Pull Request, please run the following command to check and fix any issues:

uv run poe fix-full

This command will: * Format your code using Ruff. * Check for linting errors and apply auto-fixes. * Run MyPy for static type checking.

4.1.1. General Guidelines

  • PEP8: We follow standard PEP8 guidelines, which are largely enforced by our automated tooling.

  • Line Length: Limited to 100 characters.

  • Type Hints: We encourage the use of modern Python type hints (e.g., list[str], int | None).

  • Comments: Only comment your code if you need to explain the why behind complex logic. Clear code is better than commented code.

  • Variable Naming: Follow PEP8 (snake_case). Avoid single-letter variables unless they are used in a very local, obvious context (like a loop index).

4.2. Configuration Options

New configuration options should be defined in the Pydantic models within the codebase.

  • Place new options near similar settings.

  • Provide clear descriptions and appropriate default values.

  • Ensure documentation in docs/configuration.rst is updated accordingly.

4.3. Building Documentation

Documentation is built using Sphinx.

4.3.1. Building Locally

To build the documentation locally:

uv run poe docs

The generated HTML will be available in docs/_build/html. For a better developer experience, you can use the watch command to see changes in real-time:

uv run poe docs-watch

4.3.2. CI/CD Deployment

The documentation is automatically built and deployed to GitHub Pages via GitHub Actions whenever changes are pushed to the master branch.

4.3.3. Writing Documentation

  • Documentation is written in reStructuredText (RST).

  • Configurations should include a description, default value, and any specific constraints.

  • Follow the existing hierarchy and style of the documentation.