Build and Publish Docs#

Read the Docs configuration#

Documentation publishing is controlled by .readthedocs.yaml at the repository root:

  • It defines the build environment

  • It points to the Sphinx configuration in docs/conf.py

  • It uses environment.yml for dependency resolution

Sphinx project configuration#

docs/conf.py configures:

  • API autodoc via sphinx.ext.autodoc and sphinx.ext.napoleon

  • GitHub source links via sphinx.ext.linkcode

  • HTML theme via pydata_sphinx_theme

  • Source-link git ref resolution with fallbacks: READTHEDOCS_GIT_COMMIT_HASH -> git rev-parse HEAD -> READTHEDOCS_GIT_IDENTIFIER -> main

The documentation assumes CryoSwath is installed in the build environment; the Pixi and pip commands below install it before running Sphinx.

Build locally#

Recommended (Pixi-managed, lockfile-backed):

pixi install --locked -e docs
pixi run -e docs docs-build

Alternative (pip-based local build):

pip install -r docs/requirements.txt
pip install --editable .
make -C docs html

Or directly with Sphinx:

sphinx-build -b html docs docs/_build/html

The built pages are written to docs/_build/html.

PyPI publishing#

Package publishing is handled by .github/workflows/pypi-publish.yml.

  • Creating a GitHub release automatically builds the sdist and wheel.

  • The workflow checks that the release tag matches pyproject.toml’s version (v0.2.5 -> 0.2.5).

  • If the version check passes, the workflow publishes to PyPI via GitHub trusted publishing.