Skip to content

Contributing guidelines

Development

Building the documentation

The documentation is written in Markdown and built with Zensical, the modern static site generator from the Material for MkDocs team. Zensical reads the existing mkdocs.yml directly so the source format is unchanged from a stock MkDocs project.

To build and serve the documentation for yourself:

pip install -e .[docs]
zensical serve

For a one-shot production build:

zensical build --clean

The build artefacts land in site/ (gitignored). You can find the documentation source in the docs directory. If you are adding new pages, update the listing in mkdocs.yml under the nav entry.

The documentation is hosted at proteus-framework.org/CALLIOPE.

Running tests

CALLIOPE uses pytest to run the tests. You can run them with:

pytest

To check coverage:

coverage run -m pytest
coverage report   # text summary in the terminal
coverage html     # HTML report under htmlcov/

Making a release

The versioning scheme is CalVer.

  1. Update requirements files:
python tools/generate_requirements_txt.py
pip-compile -o requirements_full.txt pyproject.toml
  1. Bump the version (release / patch as needed):
bump-my-version bump release
# e.g. 25.05.04 → 26.05.02

  1. Commit and push your changes.

  2. Create a new release on GitHub. Set the tag to the specified version, e.g. 26.05.02.

  3. The upload to PyPI is triggered when a release is published, handled by this workflow.