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 with a four-tier marker scheme (unit, smoke, integration, slow). Common selections:

pytest -m unit                              # fast in-process tests
pytest -m smoke                             # minimal-config solver tests
pytest -m integration                       # full multi-species CHNS solves
pytest -m "(unit or smoke) and not skip"    # PR-gate selection
pytest -m "not skip"                        # full nightly selection

To check coverage:

pytest --cov=src/calliope --cov-report=term -m "not skip"
pytest --cov=src/calliope --cov-report=html -m "not skip"   # htmlcov/

For details on the marker scheme, badge system, and coverage gate, see the testing suite explanation. To add a new test, see the build a new test how-to.

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. Tag the release on main (CalVer YY.MM.DD, bare tag with no leading v):
git checkout main
git pull
git tag 26.05.10
git push origin 26.05.10

setuptools-scm derives the package version from the tag at build time; no source files need editing.

  1. Create a new release on GitHub against that tag, e.g. 26.05.10.

  2. The upload to PyPI is triggered automatically when the release is published, handled by this workflow. See How-to: releasing for the full procedure.