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,68 @@
+(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.
+
+## Previewing docs on Casper
+
+There are a few different ways to do this.
+
+### Previewing docs on Casper with OnDemand
+
+```{attention}
+Your CTSM checkout will need to be in (or symlinked to) your home directory (`$HOME`) for this method to work.
+```
+
+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. 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
+```

doc/source/users_guide/working-with-documentation/building-docs-prereqs-mac.md → doc/source/users_guide/working-with-documentation/bld-prev-docs-mac.md

@@ -1,29 +1,35 @@
-.. _building-docs-prereqs-mac:
+(bld-prev-docs-mac)=
 
-# Initial setup: Mac
+# Building and previewing the documentation on Mac
+
+```{contents}
+:depth: 1
+:local:
+```
+
+## Initial Mac setup
 
 Note that you may need administrator privileges on your Mac for the installation steps detailed here.
 
-.. _building-docs-git-tools:
+(building-docs-git-tools)=
 
-## Python
+### Python
 To test whether you already have the required Python version, open a Terminal window and try the following:
 ```shell
 python3 --version
 ```
 
-If python3 is already set up, you'll see a version number. If that version is 3.7 or later, you should be ready as far as Python goes; continue to :ref:`additional-reqs`.
+If python3 is already set up, you'll see a version number. If that version is 3.7 or later, you should be ready as far as Python goes; continue to {ref}`additional-reqs`.
 
-If not, recent versions of macOS should print a messsage saying, "xcode-select: No developer tools were found, requesting install." A dialog box will then pop up that says, "The 'python3' command requires the command line developer tools. Would you like to install the tools now?" Press Install and go through the installation process. This will take a while; once it's done, test by doing ``python3 --version`` again. (You may need to open a new Terminal window.) If the printed version number looks good, continue to :ref:`additional-reqs`.
+If not, recent versions of macOS should print a messsage saying, "xcode-select: No developer tools were found, requesting install." A dialog box will then pop up that says, "The 'python3' command requires the command line developer tools. Would you like to install the tools now?" Press Install and go through the installation process. This will take a while; once it's done, test by doing ``python3 --version`` again. (You may need to open a new Terminal window.) If the printed version number looks good, continue to {ref}`additional-reqs`.
 
-..
-  The paragraph above was tested 2025-04-25 on a fresh-ish installation of macOS 15.3.2.
+% The paragraph above was tested 2025-04-25 on a fresh-ish installation of macOS 15.3.2.
 
-If instead `python3` gives "command not found," or the version is less than 3.7, you might need to install Python; continue to :ref:`aliasing-python3-to-python`. Otherwise, continue to :ref:`additional-reqs`.
+If instead `python3` gives "command not found," or the version is less than 3.7, you might need to install Python; continue to {ref}`aliasing-python3-to-python`. Otherwise, continue to {ref}`additional-reqs`.
 
-.. _aliasing-python3-to-python:
+(aliasing-python3-to-python)=
 
-### Aliasing `python3` to `python`
+#### Aliasing `python3` to `python`
 Try the same command as above, but instead of `python3` just do `python` (no number). If that version is 3.7 or later, you can tell your Mac that when you say `python3` you want it to use `python`:
 ```bash
 echo alias python3="$(which python)" >> ~/.bashrc
@@ -32,10 +38,10 @@ echo alias python3="$(which python)" >> ~/.zshrc
 
 This will make it so that bash scripts, like what we use to build our docs, know what to do for `python3`. `python3` will also be available in new Terminal sessions if your shell is `zsh` (the default since macOS 10.15) or `bash`.
 
-If you were able to do this, you can continue to :ref:`additional-reqs`. If not, continue to the next section.
+If you were able to do this, you can continue to {ref}`additional-reqs`. If not, continue to the next section.
 
-### Conda
-If your `python` doesn't exist or is too old, we suggest using Python via Conda. First, check whether you already have Conda installed: :ref:`do-i-already-have-conda` If not, install Conda (:ref:`installing-conda-for-docs`), then come back here.
+#### Conda
+If your `python` doesn't exist or is too old, we suggest using Python via Conda. First, check whether you already have Conda installed: {ref}`do-i-already-have-conda` If not, install Conda ({ref}`installing-conda-for-docs`), then come back here.
 
 Try this to check the Python version in the `base` Conda environment:
 ```shell
@@ -44,29 +50,29 @@ conda run -n base python3 --version
 
 Repeat with all your Conda environments as needed until you find one that's Python 3.7 or later. Let's say your `ENVNAME` environment works. In that case, just make sure to do `conda activate ENVNAME` before running the commands in the documentation-building instructions.
 
-.. _additional-reqs:
+(additional-reqs)=
 
-## Additional requirements
+### Additional requirements
 
-.. _container-or-conda-mac:
+(container-or-conda-mac)=
 
-### Container software or Conda environment
+#### Container software or Conda environment
 We recommend building the software in what's called a container—basically a tiny little operating system with just some apps and utilities needed by the doc-building process. This is nice because, if we change the doc-building process in ways that require new versions of those apps and utilities, that will be completely invisible to you. You won't need to manually do anything to update your setup to work with the new process; it'll just happen automatically.
 
-We recommend using the container software Podman, which you can install with Homebrew. (:ref:`install-homebrew-mac`)
+We recommend using the container software Podman, which you can install with Homebrew. ({ref}`install-homebrew-mac`)
 
 1. Install Podman with `brew install podman`.
 1. Set up and start a Podman "virtual machine" with `podman machine init --now`.
 1. Test your installation by doing `podman run --rm hello-world`. If it worked, you should see ASCII art of the Podman logo.
 
 You may not be able to install Podman or any other containerization software, so there is an alternative method: a Conda environment.
 
-1. Install Conda, if needed (see :ref:`installing-conda-for-docs`).
-1. Follow the instructions for setting up the `ctsm_pylib` Conda environment in Sect. :numref:`using-ctsm-pylib`.
+1. Install Conda, if needed (see {ref}`installing-conda-for-docs`).
+1. Follow the instructions for setting up the `ctsm_pylib` Conda environment in Sect. {numref}`using-ctsm-pylib`.
 
-.. _docs-git-tools:
+(docs-git-tools)=
 
-### Git tools
+#### Git tools
 Note: Do this section after handling Python, because the Python installation process might bring the Git tools with it.
 
 To test whether you have the required Git tools already, open a Terminal window and try the following:
@@ -75,49 +81,67 @@ git --version
 git-lfs --version
 ```
 
-If either of those fail with "command not found," you'll need to install them. The recommended way is with Homebrew. (:ref:`install-homebrew-mac`)
+If either of those fail with "command not found," you'll need to install them. The recommended way is with Homebrew. ({ref}`install-homebrew-mac`)
 
 2. Use Homebrew to [install Git](https://formulae.brew.sh/formula/git#default), if needed.
 3. Use Homebrew to [install Git LFS](https://formulae.brew.sh/formula/git-lfs#default), if needed.
 
-## Frequently-asked questions
+### Frequently-asked questions
 
-.. _what-kind-of-mac-chip:
+(what-kind-of-mac-chip)=
 
-### What kind of chip does my Mac have?
+#### What kind of chip does my Mac have?
 For certain steps in this installation process, you may need to know whether your Mac has an Intel (`x86_64`) or an Apple Silicon (`arm64`) chip. If you don't know, visit Apple's [Mac computers with Apple silicon](https://support.apple.com/en-us/116943) page for instructions.
 
-.. _install-homebrew-mac:
+(install-homebrew-mac)=
 
-### How do I install Homebrew?
+#### How do I install Homebrew?
 1. Install Homebrew using the instructions at https://brew.sh/. Make sure to follow the instructions during this process for adding Homebrew to your path.
 1. Check your installation by making sure that `brew --version` doesn't error.
 
-.. _do-i-already-have-conda:
+(do-i-already-have-conda)=
 
-### Do I already have Conda installed?
+#### Do I already have Conda installed?
 You can check whether you have Conda installed like so:
 ```shell
 conda env list
 ```
 
 If that shows you something like
 ```
-# conda environments:
-#
+## conda environments:
+##
 base           /Users/you/...
 another_env    /Users/you/.../...
 ...
 ```
 
 instead of the "command not found" error, then you do have conda installed! (Note that the second column doesn't really matter.) 
 
-.. _installing-conda-for-docs:
+(installing-conda-for-docs)=
 
-### How do I install Conda?
+#### How do I install Conda?
 We suggest installing Conda, if needed, via Miniforge:
 
-1. [Download Miniforge](https://conda-forge.org/download/) and install it. (:ref:`what-kind-of-mac-chip`) You can also [install Miniforge via Homebrew](https://formulae.brew.sh/cask/miniforge#default), if you already have that installed. (:ref:`install-homebrew-mac`)
+1. [Download Miniforge](https://conda-forge.org/download/) and install it. ({ref}`what-kind-of-mac-chip`) You can also [install Miniforge via Homebrew](https://formulae.brew.sh/cask/miniforge#default), if you already have that installed. ({ref}`install-homebrew-mac`)
 2. Activate Conda permanently in your shell by opening a new Terminal window and doing `conda init "$(basename $SHELL)"`.
 
-You should now have `conda` and an up-to-date version of `python3` available, although will need to open another new Terminal window for it to work.
+You should now have `conda` and an up-to-date version of `python3` available, although will need to open another new Terminal window for it to work.
+
+## Building docs on Mac
+Open a terminal window and navigate to your CTSM checkout. Then do:
+
+```{include} embed-build-cmd.md
+```
+
+See {ref}`container-or-conda-mac` for more information on those two methods.
+
+## Previewing docs on Mac
+
+You can open your build of the documentation in your default browser with
+```shell
+open _build/html/index.html
+```
+
+```{include} embed-preview-menu.md
+```