CONTRIBUTING.md

See the Scientific Python Developer Guide for a detailed description of best practices for developing scientific packages.

Quick development

The fastest way to start with development is to use nox. If you don't have nox, you can use uvx nox to run it without installing, or uv tool install nox. If you don't have uv, you can install it a variety of ways, including with pip, pipx, brew, and just downloading the binary (single file).

To use, run nox. This will lint and test using every installed version of Python on your system, skipping ones that are not installed. You can also run specific jobs:

$ nox -s lint  # Lint only
$ nox -s tests  # Python tests
$ nox -s docs  # Build and serve the docs
$ nox -s build  # Make an SDist and wheel

Nox handles everything for you, including setting up an temporary virtual environment for each run.

Setting up a development environment manually

You can set up a development environment by running:

uv sync

Pre-commit

You should prepare pre-commit, which will help you by checking that commits pass required checks:

uv tool install pre-commit # or brew install pre-commit on macOS
pre-commit install # Will install a pre-commit hook into the git repo

You can also/alternatively run pre-commit run (changes only) or pre-commit run --all-files to check even without installing the hook.

Testing

Use pytest to run the unit checks:

uv run pytest

Coverage

Use pytest-cov to generate coverage reports:

uv run pytest --cov=StanShock

Building docs

You can build and serve the docs using:

nox -s docs

You can build the docs only with:

nox -s docs --non-interactive