Update documentation documentation

.github/ISSUE_TEMPLATE/03_documentation.md

@@ -3,7 +3,7 @@ name: Documentation
 about: Something should be added to or fixed in the documentation
 
 ---
-
+(Please see our [contribution guidelines for documentation](https://escomp.github.io/CTSM/users_guide/working-with-documentation/docs-intro.html#contribution-guidelines).)
 
 ### What sort(s) of documentation issue is this?
 - [ ] Something is missing.

.github/PULL_REQUEST_TEMPLATE.md

@@ -22,3 +22,5 @@ Testing performed, if any:
 (https://github.com/ESCOMP/ctsm/wiki/CTSM-coding-guidelines) and review
 the list of common problems to watch out for
 (https://github.com/ESCOMP/CTSM/wiki/List-of-common-problems).**
+
+**If this PR changes the CTSM web documentation, please see our [contribution guidelines for documentation](https://escomp.github.io/CTSM/users_guide/working-with-documentation/docs-intro.html#contribution-guidelines).**

.gitmodules

@@ -124,7 +124,7 @@ fxDONOTUSEurl = https://github.com/ESMCI/mpi-serial
 [submodule "doc-builder"]
 path = doc/doc-builder
 url = https://github.com/ESMCI/doc-builder
-fxtag = v2.2.6
+fxtag = v3.0.1
 fxrequired = ToplevelOptional
 # Standard Fork to compare to with "git fleximod test" to ensure personal forks aren't committed
 fxDONOTUSEurl = https://github.com/ESMCI/doc-builder

doc/ctsm-docs_container/Dockerfile

@@ -29,4 +29,4 @@ CMD ["/bin/bash", "-l"]
 
 LABEL org.opencontainers.image.title="Container for building CTSM documentation"
 LABEL org.opencontainers.image.source=https://github.com/ESCOMP/CTSM
-LABEL org.opencontainers.image.version="v1.0.2e"
+LABEL org.opencontainers.image.version="v2.0.1a"

doc/ctsm-docs_container/README.md

@@ -33,21 +33,22 @@ Here's where you need to specify the version number in the Dockerfile:
 ```docker
 LABEL org.opencontainers.image.version="vX.Y.Z"
 ```
-The string there can technically be anything as long as (a) it starts with a lowercase `v` and (b) it hasn't yet been used on a published version of the container.
+The string there can technically be anything as long as (a) it starts with a lowercase `v` and (b) it hasn't yet been used on a published version of the container. You may need to "bump" the version string in order for various tests to pass; if so, just add a lowercase letter at the end.
 
 You can check the results of the automatic publication on the [container's GitHub page](https://github.com/ESCOMP/CTSM/pkgs/container/ctsm%2Fctsm-docs).
 
 ### Updating doc-builder
 After the new version of the container is published, you will probably want to tell [doc-builder](https://github.com/ESMCI/doc-builder) to use the new one. Open a PR where you change the tag (the part after the colon) in the definition of `DEFAULT_IMAGE` in `doc_builder/build_commands.py`. Remember, **use the version number**, not "latest".
 
-## Publishing manually (NOT recommended)
+## Publishing manually
 
-It's vastly preferable to let GitHub build and publish the new repo using the `docker-image-build-publish.yml` workflow as described above. However, if you need to publish manually for some reason, here's how.
+It's vastly preferable to let GitHub build and publish the new repo using the `docker-image-build-publish.yml` workflow as described above. However, you may need to publish manually if, for instance, you introduce a change that breaks `doc-builder`. You could work around that by first merging a CTSM `master` PR that updates the container, then updating `doc-builder` to use it, then updating CTSM to use the new `doc-builder`. That's not always practical, though, so here's how to publish the container manually.
 
 ### Building the multi-architecture version
 
 When publishing our container, we need to make sure it can run on either arm64 or amd64 processor architecture. This requires a special build process:
 ```shell
+podman manifest rm ctsm-docs-manifest 2>/dev/null
 podman manifest create ctsm-docs-manifest
 podman build --platform linux/amd64,linux/arm64  --manifest ctsm-docs-manifest .
 ```
@@ -66,16 +67,17 @@ export HISTCONTROL=ignoreboth
 ```
 
 ### Tagging
-You'll next need to tag the image. Lots of container instructions tell you to use the `latest` tag, and Podman may actually add that for you. However, `latest` can lead to support headaches as users think they have the right version but actually don't. Instead, you'll make a new version number incremented from the [previous one](https://github.com/ESCOMP/CTSM/pkgs/container/ctsm%2Fctsm-docs/versions), in the `vX.Y.Z` format.
+You'll next need to tag the image. Lots of container instructions tell you to use the `latest` tag, and Podman may actually add that for you. However, using `latest` in `doc-builder` can lead to support headaches as users think they have the right version but actually don't. So in addition to `latest`, you'll make a new version number incremented from the [previous one](https://github.com/ESCOMP/CTSM/pkgs/container/ctsm%2Fctsm-docs/versions), in the `vX.Y.Z` format.
 
-Copy the relevant image ID (see `podman images` instructions above) and tag it with your version number like so:
+Tag the manifest with your version number like so:
 ```shell
-podman tag 6464f26339bc ghcr.io/escomp/ctsm/ctsm-docs:vX.Y.Z
+podman tag ctsm-docs-manifest ghcr.io/escomp/ctsm/ctsm-docs:v2.0.1
 ```
 
 Push to the repo:
 ```shell
 podman manifest push --all ctsm-docs-manifest ghcr.io/escomp/ctsm/ctsm-docs:vX.Y.Z
+podman manifest push --all ctsm-docs-manifest ghcr.io/escomp/ctsm/ctsm-docs:latest
 ```
 
 Then browse to the [container's GitHub page](https://github.com/ESCOMP/CTSM/pkgs/container/ctsm%2Fctsm-docs) to make sure this all worked and the image is public.

doc/ctsm-docs_container/requirements.txt

@@ -2,5 +2,5 @@
 rst2pdf == 0.103.1
 sphinx == 8.2.3
 sphinxcontrib_programoutput == 0.18
-sphinx-mdinclude == 0.6.2
+myst-parser == 5.0.0
 sphinx_rtd_theme == 3.0.2

doc/source/users_guide/using-clm-tools/paramfile-tools.md

@@ -3,7 +3,7 @@
 
 This guide describes the features and usage of the `query_paramfile` and `set_paramfile` tools, located in `tools/param_utils/`. These utilities help users inspect and modify CLM parameter files.
 
-Note that you need to have the `ctsm_pylib` conda environment activated to use these tools. See Sect. :numref:`using-ctsm-pylib` for more information.
+Note that you need to have the `ctsm_pylib` conda environment activated to use these tools. See Sect. {numref}`using-ctsm-pylib` for more information.
 
 ## `query_paramfile`
 **Purpose:** Print the values of one or more parameters from a CTSM parameter file (netCDF format).

doc/source/users_guide/working-with-documentation/bld-prev-docs-casper.md

@@ -0,0 +1,77 @@
+(bld-prev-docs-casper)=
+
+# Building and previewing the documentation on Casper (RECOMMENDED)
+
+```{contents}
+:depth: 1
+:local:
+```
+
+## 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.
+
+## 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:
+
+```{include} embed-build-cmd.md
+```
+
+See the "Container software or Conda environment" sections for {ref}`Mac <container-or-conda-mac>` or {ref}`Windows <container-or-conda-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](https://ncarhpcusergroup.slack.com/archives/C044MS8N3UP/p1775511217126589) for more information.
+```
+
+## Previewing docs on Casper
+
+There are a few different ways to do this.
+
+### 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](https://ondemand.hpc.ucar.edu/pun/sys/dashboard). After you [open a new Casper Login VNC Desktop session](https://ondemand.hpc.ucar.edu/pun/sys/dashboard/batch_connect/sys/login_desktop_ncar/session_contexts/new), 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.
+
+### 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:
+```shell
+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:
+```shell
+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](https://ncar-hpc-docs.readthedocs.io/en/latest/pbs/#qinteractive).)
+
+Once your interactive compute session is open, start the web server in it like so (again replacing `YOUR_PORT`):
+```shell
+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.
+
+### 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.
+
+### A note about previewing the docs
+
+```{include} embed-preview-menu.md
+```