Merge pull request #3184 from samsrabin/docs-bugfixes-20250527

samsrabin · web-flow · commit 35cc54f0d7a8 · 2025-05-29T11:37:17.000-06:00
ctsm5.3.050: Doc infrastructure and docs: fixes and improvements
diff --git a/.github/ISSUE_TEMPLATE/03_documentation.md b/.github/ISSUE_TEMPLATE/03_documentation.md
@@ -5,9 +5,9 @@ about: Something should be added to or fixed in the documentation
 ---
 
 
-### What sort(s) of issue is this?
+### What sort(s) of documentation issue is this?
 - [ ] Something is missing.
-- [ ] Something is (or might be) incorrect.
+- [ ] Something is (or might be) incorrect or outdated.
 - [ ] Something is confusing.
 - [ ] Something is broken.
 
diff --git a/.github/workflows/docker-image-common.yml b/.github/workflows/docker-image-common.yml
@@ -87,7 +87,7 @@ jobs:
       - name: Build docs using Docker (Podman has trouble on GitHub runners)
         id: build-docs
         run: |
-          cd doc && ./build_docs -b ${PWD}/_build -c -d --container-cli-tool docker -i $IMAGE_TAG
+          cd doc && ./build_docs -b ${PWD}/_build -c -d -i $IMAGE_TAG
 
 
   check-version:
diff --git a/.github/workflows/docs-build-and-deploy.yml b/.github/workflows/docs-build-and-deploy.yml
@@ -51,7 +51,7 @@ jobs:
         run: |
           bin/git-fleximod update -o
           cd doc
-          ./build_docs_to_publish -d --container-cli-tool docker --site-root https://escomp.github.io/CTSM
+          ./build_docs_to_publish -d --site-root https://escomp.github.io/CTSM
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -56,4 +56,4 @@ jobs:
       - name: Build docs using Docker (Podman has trouble on GitHub runners)
         id: build-docs
         run: |
-          cd doc && ./build_docs -b ${PWD}/_build -c -d --container-cli-tool docker
+          cd doc && ./build_docs -b ${PWD}/_build -c -d
diff --git a/.gitmodules b/.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.3
+fxtag = v2.2.6
 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
diff --git a/doc/ChangeLog b/doc/ChangeLog
@@ -1,4 +1,123 @@
 ===============================================================
+Tag name: ctsm5.3.050
+Originator(s): samrabin (Sam Rabin)
+Date: Thu May 29 11:26:21 MDT 2025
+One-line Summary: Fix Linux Podman; prefer Linux Docker; update docs docs.
+
+Purpose and description of changes
+----------------------------------
+
+- Fixes Podman builds on Ubuntu (mostly; see ESMCI/doc-builder#27)
+- Docker now preferred on non-Mac systems
+- Improves docs docs
+
+Significant changes to scientifically-supported configurations
+--------------------------------------------------------------
+
+Does this tag change answers significantly for any of the following physics configurations?
+(Details of any changes will be given in the "Answer changes" section below.)
+
+    [Put an [X] in the box for any configuration with significant answer changes.]
+
+[ ] clm6_0
+
+[ ] clm5_0
+
+[ ] ctsm5_0-nwp
+
+[ ] clm4_5
+
+
+Bugs fixed
+----------
+List of CTSM issues fixed (include CTSM Issue # and description):
+- [Issue #3163: Docs docs: Extraneous variable in a command](https://github.com/ESCOMP/CTSM/issues/3163)
+
+Notes of particular relevance for users
+---------------------------------------
+
+User's Guide section on docs updated with new instructions.
+
+
+Notes of particular relevance for developers:
+---------------------------------------------
+
+Caveats for developers (e.g., code that is duplicated that requires double maintenance):
+- If you're running doc/testing.sh locally, you'll need both Docker and Podman installed.
+
+
+Testing summary:
+----------------
+
+All required testing happened in GitHub workflows on the PR.
+
+
+Other details
+-------------
+
+List any git submodules updated: doc-builder
+
+Pull Requests that document the changes (include PR ids):
+- [Pull Request #3184: ctsm5.3.050: Doc infrastructure and docs: fixes and improvements by samsrabin](https://github.com/ESCOMP/CTSM/pull/3184)
+
+===============================================================
+===============================================================
+Tag name: ctsm5.3.049
+Originator(s): samrabin (Sam Rabin)
+Date: Tue May 27 12:49:00 MDT 2025
+One-line Summary: Switch docs to use Podman
+
+Purpose and description of changes
+----------------------------------
+
+Updates doc-builder to a version that prefers to use podman instead of docker. Also updates documentation to instruct docs-writers to use Podman instead of Docker, along with some other improvements.
+
+
+Significant changes to scientifically-supported configurations
+--------------------------------------------------------------
+
+Does this tag change answers significantly for any of the following physics configurations?
+(Details of any changes will be given in the "Answer changes" section below.)
+
+    [Put an [X] in the box for any configuration with significant answer changes.]
+
+[ ] clm6_0
+
+[ ] clm5_0
+
+[ ] ctsm5_0-nwp
+
+[ ] clm4_5
+
+
+Bugs fixed
+----------
+[Remove any lines that don't apply. Remove entire section if nothing applies.]
+
+List of CTSM issues fixed (include CTSM Issue # and description) [one per line]:
+
+Notes of particular relevance for users
+---------------------------------------
+
+User's Guide section on docs updated with new instructions.
+
+
+Testing summary:
+----------------
+
+All required testing happened in GitHub workflows on the PR.
+
+
+Other details
+-------------
+
+List any git submodules updated: doc-builder
+
+Pull Requests that document the changes (include PR ids):
+- [Pull Request #3153: ctsm5.3.049: Preferentially use Podman for ctsm-docs container by samsrabin](https://github.com/ESCOMP/CTSM/pull/3153)
+
+===============================================================
+===============================================================
 Tag name: ctsm5.3.048
 Originator(s): samrabin (Sam Rabin, UCAR/TSS)
 Date: Mon May 26 18:30:59 MDT 2025
diff --git a/doc/ChangeSum b/doc/ChangeSum
@@ -1,5 +1,7 @@
 Tag                   Who      Date  Summary
 ============================================================================================================================
+       ctsm5.3.050 samrabin 05/29/2025 Fix Linux Podman; prefer Linux Docker; update docs docs.
+       ctsm5.3.049 samrabin 05/27/2025 Switch docs to use Podman
        ctsm5.3.048 samrabin 05/26/2025 Automatically publish docs to this repo
        ctsm5.3.047 samrabin 05/26/2025 Merge b4b-dev to master
        ctsm5.3.046   rgknox 05/26/2025 For FATES set itype to ispval and a few unused variables to nan to help prevent future problems
diff --git a/doc/ctsm-docs_container/Dockerfile b/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.2b"
+LABEL org.opencontainers.image.version="v1.0.2c"
diff --git a/doc/doc-builder b/doc/doc-builder
@@ -1 +1 @@
-Subproject commit 4ad641bd6f18007e2599ae4ef526153c8bc1154d
+Subproject commit 3ab6d06971e508f2886f0079db37156ab93c2b07
diff --git a/doc/source/users_guide/working-with-documentation/building-docs-multiple-versions.rst b/doc/source/users_guide/working-with-documentation/building-docs-multiple-versions.rst
@@ -5,13 +5,15 @@ Building multiple versions of the documentation
 
 There is a menu in the lower left of the webpage that lets readers switch between different versions of the documentation. To build a website with this menu properly set up—so that all our versions appear and all the links work—you need to use ``docs/build_docs_to_publish`` instead of ``docs/build_docs``.
 
-If you'd like to try, this will generate a local site for you in ``_publish/`` and then open it:
+Note that this is not necessary in order for you to contribute an update to the documentation. GitHub will test this automatically when you open a PR. But if you'd like to try, this will generate a local site for you in ``_publish/`` and then open it:
 
 .. literalinclude:: ../../../testing.sh
    :start-at: ./build_docs_to_publish
    :end-before: VERSION LINKS WILL NOT RESOLVE
    :append: open _publish/index.html
 
+**Note:** This is not yet supported with Podman on Linux (including Ubuntu VM on Windows). See `doc-builder Issue #27: build_docs_to_publish fails on Linux (maybe just Ubuntu?) with Podman <https://github.com/ESMCI/doc-builder/issues/27>`_.
+
 
 How this works
 --------------
diff --git a/doc/source/users_guide/working-with-documentation/building-docs-prereqs-mac.md b/doc/source/users_guide/working-with-documentation/building-docs-prereqs-mac.md
@@ -12,14 +12,14 @@ To test whether you already have the required Python version, open a Terminal wi
 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:`docs-git-tools`.
+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:`docs-git-tools`.
+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.
 
-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`.
+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:
 
@@ -32,59 +32,41 @@ 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:`docs-git-tools`.
+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:
-```shell
-conda env list
-```
-
-If that shows you something like
-```
-# conda environments:
-#
-base           /Users/you/...
-another_env    /Users/you/.../...
-...
-```
+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.
 
-instead of the "command not found" error, then you do have conda installed! (Note that the second column doesn't really matter.) Try this to check the Python version in the `base` Conda environment:
+Try this to check the Python version in the `base` Conda environment:
 ```shell
 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.
 
-If you don't have Conda yet, go on to the next section. Otherwise, continue to :ref:`docs-git-tools`.
-
-.. _installing-conda-for-docs:
-
-### Installing Conda
-We suggest installing Conda, if needed, via Miniforge:
+.. _additional-reqs:
 
-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)"`.
+## Additional requirements
 
-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.
+.. _container-or-conda-mac:
 
-## Additional requirements
-The remaining software you need to install depends on which documentation-building method(s) you plan to use.
+### 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.
 
-### Container (recommended)
-We use Podman to build and run our containers. The recommended way to install Podman is 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.
 
-### Non-container method
+You may not be able to install Podman or any other containerization software, so there is an alternative method: a Conda environment.
 
-Install Conda, if needed (see :ref:`installing-conda-for-docs`). Then 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:
 
-## 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:
@@ -109,4 +91,33 @@ For certain steps in this installation process, you may need to know whether you
 
 ### 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.
+1. Check your installation by making sure that `brew --version` doesn't error.
+
+.. _do-i-already-have-conda:
+
+### 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:
+#
+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:
+
+### 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`)
+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.
diff --git a/doc/source/users_guide/working-with-documentation/building-docs-prereqs-windows.md b/doc/source/users_guide/working-with-documentation/building-docs-prereqs-windows.md
diff --git a/doc/source/users_guide/working-with-documentation/docs-intro-and-recommended.md b/doc/source/users_guide/working-with-documentation/docs-intro-and-recommended.md
diff --git a/doc/testing.sh b/doc/testing.sh
