Development¶

Running the test suite¶

Install the test dependencies (see Installation) and run:

pytest -n auto -v tests/

Three test groups exist:

Directory	What is tested
`tests/zephyr/`	Core logic: grid handling, clipping, unrotation, attribute addition
`tests/find_files/`	Path construction and date-range file selection
`tests/requests/`	Per-dataset request processing — requires access to `/net/atmos/data`, so this group only passes on an IAC machine (see Installation)

CI/CD¶

Pipeline	Trigger	What it does
GitHub Action `pytest` (`.github/workflows/pytest.yml`)	Push	Runs the full pytest suite on `iacdipl-7.ethz.ch` (via ssh, proxied through `fog.ethz.ch`), since `tests/requests` needs real dataset access. Full git history is checked out so `setuptools_scm` can derive an accurate version from `git describe --tags`.
GitHub Action `autoyapf` (`.github/workflows/autoyapf.yml`)	Push (non-`main`)	Auto-formats Python files with PEP 8 style and pushes the result back to the branch.
GitHub Action `docs` (`.github/workflows/docs.yml`)	Push to `main` touching `docs/**` (or manual dispatch)	Builds this Sphinx site and deploys it to the `gh-pages` branch, published at https://c2sm.github.io/zephyr/docs/.
GitHub Action `docs preview` (`.github/workflows/docs_preview.yml`)	PR opened/updated, touching the same paths as `docs`	Builds the site and deploys it to `gh-pages` under `docs/pr-<number>/`, then comments the preview link on the PR (updating the same comment on subsequent pushes). The preview folder is removed and the comment left in place when the PR closes.

Generating the frontend’s dataset metadata (file_tree_*.json, meta_*.json) used to run here as the Jenkins FileIndex and FileSizeNumber jobs; that logic and its scheduled GitHub Actions workflows now live in C2SM/iac-metadata.

Versioning¶

The package version is derived automatically from the latest git tag via setuptools_scm (see [tool.setuptools_scm] in pyproject.toml) — src/zephyr/_version.py is generated at install/build time and is not tracked in git. There’s no file to bump by hand; cutting a release is just tagging the commit.

Building the documentation locally¶

This site is built with Sphinx, using MyST Markdown so pages are plain .md files.

uv sync --extra docs
uv run sphinx-build -b html docs docs/_build/html

Then open docs/_build/html/index.html in a browser. To rebuild and reload the browser automatically on changes, use tools/serve_docs.sh instead, which serves the site at http://127.0.0.1:8000:

tools/serve_docs.sh

(Under the hood this runs sphinx-autobuild, which isn’t pinned in pyproject.toml and is pulled in ad hoc via uv run --with.)

Contributing¶

Formatting is enforced automatically by the autoyapf GitHub Action — you don’t need to run a formatter locally before pushing to a non-main branch.
Add tests alongside new logic in the matching tests/ subdirectory (see the table above); anything touching file discovery or extraction that needs real data belongs in tests/requests/ and will only run in CI (or locally on an IAC machine).
Keep this documentation in sync: if you change the request schema, supported datasets, or the processing flow, update the relevant page under docs/ in the same PR.