Contributor Guide

Contributor Guide#

Editable / development install#

git clone https://github.com/nansencenter/xhycom.git
cd xhycom
pip install -e .            # core (includes Dask + xgcm)
pip install -e ".[dev]"     # with test dependencies

Running the tests#

pytest

The dev extra (pytest, pytest-cov, netCDF4) plus the core dependencies is enough to run the reader, postprocessing, and vertical-regridding tests, they’re self-contained, with real-data fixtures bundled under tests/data/.

The lateral (horizontal) regridding tests additionally need xesmf, so they self-skip (pytest.importorskip("xesmf")) unless it’s installed. To run the full suite including those, use the conda environment from Horizontal regridding needs xESMF (conda):

conda env create -f ci/environment-regrid.yml
conda activate hycom-analysis-env
pytest

Pre-commit hooks#

The project uses pre-commit to run linting/formatting (ruff) and basic file checks before each commit. It’s already installed if you followed either of the setups above, it’s in the dev extra (pip install -e ".[dev]") and in ci/environment-regrid.yml. Otherwise, install it directly:

pip install pre-commit

Then install the git hook so the checks run automatically on git commit:

pre-commit install

Without this step, the hooks won’t run locally, they’ll only run in CI, where they’re required to pass before a PR can merge.

To run all hooks manually against the full codebase (e.g. before opening a PR):

pre-commit run --all-files

Building the documentation locally#

The documentation is built with Sphinx using MyST-NB, so Markdown files and Jupyter notebooks render directly.

Set up the environment#

A conda environment with all required packages is provided in docs/environment.yml:

conda env create -f docs/environment.yml
conda activate xhycom-docs

If you already have a conda environment for xhycom, you can install the docs dependencies into it instead:

conda activate <your-env>
pip install -e ".[docs]"

Build#

Run from the docs/ directory:

cd docs
make html

Then open docs/_build/html/index.html in a browser. Other useful targets:

make clean   # remove the build directory
make help    # list all available targets

Previewing documentation changes in a PR#

To see how your changes to the documentation render, you have two options:

  1. Build the documentation locally, see Build above for instructions.

  2. After pushing your changes to the PR, once the Read the Docs build has finished, click the yellow link in the PR’s checks list (as shown below) to preview the rendered docs for this PR:

    Read the Docs PR check with the Details link highlighted

Adding or editing pages#

  • All documentation lives in docs/ as Markdown files and Jupyter notebooks.

  • The table of contents is defined in the {toctree} block in docs/index.md.

  • To add a new page, create a .md or .ipynb file in docs/ and add its name (without extension) to the toctree block in docs/index.md.