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):

.. code-block:: sh

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

Alternative (pip-based local build):

.. code-block:: sh

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

Or directly with Sphinx:

.. code-block:: sh

   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.