Contributing

All configuration for the project should be put into pyproject.toml.

Working locally¶

1. Create a virtualenv using whatever method you like ( eg, virtualenvwrapper)

uv venv

1. Sync venv

uv sync --all-extras --all-packages --all-groups

Running tests locally¶

To run a subset of the required tests, run the smoke test script

./scripts/smoke.bash

If on Windows, you should be able to just run the ‘tox’ commands in that file.

Updating/adding a dependency¶

1. Add or update the dependency in pyproject.toml

2. Update lock file

uv lock --upgrade

1. Sync venv

uv sync --all-extras --all-packages --all-groups

1. Run tests as above

Pre-commit¶

Basic checks (formatting, import order) are done with pre-commit and are controlled by the yaml file.

After installing dependencies, Run

# check it works
pre-commit run --all-files
pre-commit install

Run every so often to update the pre-commit hooks

pre-commit autoupdate

Fixing Python formatting issues¶

ruff format tavern/ tests/
ruff --fix tavern/ tests/

Fix yaml formatting issues¶

pre-commit run --all-files

Creating a new release¶

1. Setup ~/.pypirc according to the official instructions

2. Tag and push to git with tbump <new-tag> --tag-message "<tag-message>"

3. Upload to pypi with flit publish

Building the documentation¶

Run this standalone for now: jupyter-book/mystmd#2082

uv tool run --from mystmd myst build --html

Watching for changes¶

To automatically rebuild when files in the docs/ folder change:

uv tool run watchfiles "uv tool run --from mystmd myst build --html" --filter all docs myst.yml