1.10.2. Building and previewing the documentation on Casper (RECOMMENDED)

1.10.2.1. Initial Casper setup

You don't need to install any software! This is why Casper is the recommended method for building and previewing the docs.

1.10.2.2. Building docs on Casper

Casper uses the Podman software for running containers like the one we recommend for building the CTSM documentation. Make sure it's enabled before building: module load podman. Then do:

cd doc
./build_docs -b _build -c -d

This runs a complicated series of scripts and software that culminate in something called Sphinx converting the .rst and .md files into HTML webpages, all within the (new, if needed) _build directory.

The -c means "do a clean build." If you leave it off, Sphinx will only rebuild files it thinks have changed since the last time you built the docs, which is faster but can lead to problems. If you get unexpected results or errors without -c, rerunning with -c is the first troubleshooting step.

The -d means "run using the container." If you're not using the container and are instead using the ctsm_pylib Conda environment (not recommended), leave off -d, and make sure you've activated ctsm_pylib before running the above command.

(Do ./build_docs --help for more information and options.)

See the "Container software or Conda environment" sections for Mac or Windows for more information on these two methods.

Tip

[2026-04-07] If you get an error saying something like Error: could not find a working conmon binary, do this and retry:

module load ncarenv/24.12
module load podman

The bug making this necessary should hopefully be resolved soon. It has to do with the installation of podman in the module ncarenv/25.10; see this Slack thread for more information.

1.10.2.3. Previewing docs on Casper

There are a few different ways to do this.

1.10.2.3.1. Previewing docs on Casper with OnDemand

Tip

This will be somewhat easier if your CTSM checkout is in (or symlinked to) your home directory ($HOME).

The simplest way to preview your built documentation on Casper is to use NCAR's OnDemand service. After you open a new Casper Login VNC Desktop session, wait for it to start, then click the "Launch Casper Login VNC Desktop" button. This will open a Linux desktop in your browser. Click on the "Home" icon and navigate to your CTSM checkout, then the doc/_build/html directory, then open the index.html file. (If your checkout isn't in your home directory, you'll need to click on Devices > / in the sidebar of the window that opens, then navigate all the way to your checkout.) That should open it in the Linux desktop's Firefox, at which point you can browse around as usual.

If you rebuild the documentation but don't see your changes updated in the webpage, and the reload button doesn't work, you may need to navigate to a different page and then come back.

1.10.2.3.2. Previewing docs on Casper via SSH tunnel

If the OnDemand method doesn't work for whatever reason, open a terminal on your local machine and do this:

ssh YOUR_USERNAME@casper.hpc.ucar.edu echo $((10000 + $(id -u) % 50000))

This will print an integer that we will call YOUR_PORT.

Then open a new SSH connection to the server like so, replacing YOUR_PORT with the integer you got above:

ssh -L YOUR_PORT:localhost:YOUR_PORT YOUR_USERNAME@casper.hpc.ucar.edu

Once that's connected, we're going to spin up a web server. It's best to do this on a compute node rather than a login node. Use the qinteractive command to open an interactive session on a Casper compute node. (Find more info about qinteractive here.)

Once your interactive compute session is open, start the web server in it like so (again replacing YOUR_PORT):

cd /path/to/your/ctsm/repo
cd doc/_build/html
python3 -m http.server YOUR_PORT

Now you're ready to view your documentation! Just open a web browser on your computer and navigate to http://localhost:YOUR_PORT. You should see a rendered version of the documentation that you can browse as usual.

1.10.2.3.3. Fallback preview method

If neither of the above work, you can download the doc/_build/html directory to your computer (e.g., with scp or rsync) and open html/index.html in a web browser.

1.10.2.3.4. A note about previewing the docs

Note that there is a menu in the lower left of the webpage that lets readers switch between different versions of the documentation. The links to versions in this menu will not work when using the build command given above. If you wish to preview this version switching functionality, see Building multiple versions of the documentation.