Setting up development environment

This document describes how to set up a development environment for building and testing the documentation and running the test-suite locally.

This project is managed by uv.

A Makefile is provided for convenience to automate common development tasks.

Create a virtual environment and install the dev dependencies:

# Using Makefile
make install

# Or directly with uv
uv sync --group dev

This will both download dependencies to test and build the documentation. Other possible dependency groups are test and docs.

Pre commit checks with pre-commit

This project uses pre-commit to manage git hooks for code quality checks. To install the git hooks, run: .. code-block:: bash

uv run –group dev pre-commit install

Running Tests and Linting

You can run all quality checks (lint, format, typecheck, and tests) using:

make check

Individual checks:

make lint       # Run ruff
make typecheck  # Run mypy
make test       # Run pytest

Building Documentation

To build the HTML docs into “docs/build/html”:

# Using Makefile
make docs

# Or directly with uv
uv run --group docs make html -C docs

The documentation uses asciinema to capture output from the terminal from animations. This cast is then converted to a gif using aggcast. To update the animations, install asciinema and aggcast and then run the following command from the root of the repository:

make casts
make casts-interactive
make aggconvert
make docs

This will re-generate all asciinema gifs in the documentation and update the documentation.