Developers guide¶

Installation¶

This project uses uv to manage the virtual environment. To install the project, run:

uv sync
uv run pre-commit install --install-hooks

This will create a virtual environment in .venv and install the dependencies listed in pyproject.toml.

You can then go on to build docs, run tests, etc. using uv run commands.

We use mkdocs and mkdocs material to maintain documentation. You can test them locally with:

uv run mkdocs serve

:note: mkdocs material uses a superset of Markdown, see the reference

Docs are automatically published to gh-pages branch via. Github actions after a PR is merged into master.

We use pytest to run tests. You can run them with:

uv run pytest

You can also run tests with coverage using:

uv run pytest --cov=.

There are several workflows in .github/workflows:

docs.yml - Deploys documentation to github pages on push to master (e.g. after PR merged)
release.yml - Drafts release notes based on merged PR's
labeler.yml - Sets the repository to use the issue labels defined in .github/labels.yml
test.yml - Runs tests on PR's or on push to master (e.g. after PR merged)

Each PR should have a major/minor/patch label assigned based on the desired version increment, e.g. minor will go from x.y.z -> x.(y+1).z
After a PR is merged then draft release notes will be generated/updated here (see release.yml above)
In the Github UI: rewrite the drafts into something informative to a user and then click release
- :warning: Releases should be made little and often - commits on master are immediately visible to cookiecutter users