Skip to main content

Contributing

Contributions are welcome as issues and pull requests on GitHub. This page covers setting up a development environment and building this documentation. AGENTS.md holds the full development guidelines and the reasoning behind the design.

Set up and test

The project uses uv. These commands install the environment and run the checks that every pull request must pass:

uv sync
uv run pytest
uv run ruff format
uv run ruff check --fix
uv run pyrefly check

The default tests run offline. Tests that download data or run SNAP are marked integration and run with uv run pytest -m integration if CDSE credentials and a SNAP installation are available.

Check the prose

Vale checks the Markdown and Quarto files. It is installed separately, not through uv. .vale.ini sets the rules and gives the reason for each rule that is off. Download the rule packages once, then check the tracked files:

vale sync
vale $(git ls-files '*.md' '*.qmd')

When the spelling check reports a correct term, add it to .vale/styles/config/vocabularies/s1bursts/accept.txt.

Build the documentation

The site is built with Great Docs, which also needs Quarto. Guide pages live in user_guide/, the API reference comes from the docstrings, and great-docs.yml configures the site:

uv sync --group docs
uv run great-docs build
uv run great-docs preview

The build writes the site to great-docs/_site/, which is generated and never edited by hand.

Frozen tutorials

The tutorials download real data and run SNAP, which takes too long for every build. Their results are therefore frozen: _freeze/ stores each page’s rendered output and figures, and builds reuse it without running the code. CI builds the site from _freeze/ alone, without credentials or SNAP.

Refresh a frozen page after changing its code, its text or the API it uses. The frozen output includes the text, so the site shows an edit only after the page is refreshed. This reruns the page, so it needs .env and SNAP. Downloads and products are cached in cache/docs/ and reused. Refresh one page per command, then rebuild:

uv run great-docs freeze user_guide/10-glacier-backscatter.qmd
uv run great-docs build

Review the new figures and the _freeze/ diff before committing. Each frozen page ends with its run details: the date, the s1bursts version and the SNAP version it was run with.