Contributor Guide

Building the documentation locally

The documentation is built with Sphinx using the MyST parser so that Markdown files are rendered directly.

Set up the environment

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

conda env create -f docs/environment.yaml
conda activate hycom-cice-docs

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

conda activate <your-env>
pip install -r docs/requirements.txt

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 latex   # build a PDF via LaTeX
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.

  • The table of contents is defined in docs/index.rst.

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