Merge master to alpha-ctsm5.4.CMIP7

.git-blame-ignore-revs

@@ -67,3 +67,6 @@ cdf40d265cc82775607a1bf25f5f527bacc97405
 3b7a2876933263f8986e4069f5d23bd45635756f
 3dd489af7ebe06566e2c6a1c7ade18550f1eb4ba
 742cfa606039ab89602fde5fef46458516f56fd4
+4ad46f46de7dde753b4653c15f05326f55116b73
+75db098206b064b8b7b2a0604d3f0bf8fdb950cc
+84609494b54ea9732f64add43b2f1dd035632b4c

.github/workflows/check-clm6-aliases.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+set -e
+
+# Check that clm6* compset aliases return CLM6* longnames
+
+# Change to top level of clone
+cd "$(git rev-parse --show-toplevel)"
+
+# Check that query_config can run without error
+cime/scripts/query_config --compsets 1>/dev/null
+
+# Find bad compsets
+OLD_IFS=$IFS
+IFS='\n'
+set +e
+# Relies on case sensitivity here: Alias should have Clm6 and longname should have CLM6
+bad_compsets="$(cime/scripts/query_config --compsets | sort | uniq | grep Clm6 | grep -v CLM6)"
+set -e
+if [[ "${bad_compsets}" != "" ]]; then
+    echo "One or more compsets with Clm6 alias but not CLM6 longname:" >&2
+    echo $bad_compsets  >&2
+    exit 1
+fi
+
+exit 0

.github/workflows/check-clm6-aliases.yml

@@ -0,0 +1,40 @@
+name: Check that clm6* compset aliases return CLM6* longnames
+# Only check files in our repo that AREN'T in submodules
+# Use a Python command to check each file because xmllint isn't available on GH runners
+
+on:
+  push:
+    # Run when a change to these files is pushed to any branch. Without the "branches:" line, for some reason this will be run whenever a tag is pushed, even if the listed files aren't changed.
+    branches: ['*']
+    paths:
+      - '.github/workflows/check-clm6-aliases.sh'
+      - 'cime/**'
+      - 'cime_config/config_compsets.xml'
+
+  pull_request:
+    # Run on pull requests that change the listed files
+    paths:
+      - '.github/workflows/check-clm6-aliases.sh'
+      - 'cime/**'
+      - 'cime_config/config_compsets.xml'
+
+  workflow_dispatch:
+
+jobs:
+  check-clm6-aliases:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Checkout submodules
+        run: |
+          bin/git-fleximod update
+
+      - name: Install xmllint for CIME
+        run: |
+          sudo apt-get update && sudo apt-get install --no-install-recommends -y libxml2-utils
+
+      - name: Check aliases
+        run: |
+          .github/workflows/check-clm6-aliases.sh

.github/workflows/docker-image-build.yml

@@ -1,5 +1,5 @@
 # Modified from https://docs.github.com/en/packages/managing-github-packages-using-github-actions-workflows/publishing-and-installing-a-package-with-github-actions#publishing-a-package-using-an-action (last accessed 2025-05-09)
-name: Test building ctsm-docs Docker image and using it to build the docs
+name: Build and test ctsm-docs container
 
 # Configures this workflow to run every time a change in the Docker container setup is pushed or included in a PR
 on:
@@ -9,15 +9,13 @@ on:
     paths:
       - 'doc/ctsm-docs_container/**'
       - '!doc/ctsm-docs_container/README.md'
-      - '.github/workflows/docker-image-ctsm-docs-build.yml'
       - '.github/workflows/docker-image-common.yml'
 
   pull_request:
     # Run on pull requests that change the listed files
     paths:
       - 'doc/ctsm-docs_container/**'
       - '!doc/ctsm-docs_container/README.md'
-      - '.github/workflows/docker-image-ctsm-docs-build.yml'
       - '.github/workflows/docker-image-common.yml'
 
   workflow_dispatch:

.github/workflows/docker-image-common.yml

@@ -76,14 +76,16 @@ jobs:
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
 
-      # Try building our docs using the new container
-      - name: Checkout doc-builder external
+      # Check out all submodules because we might :literalinclude: something from one
+      - name: Checkout all submodules
         run: |
-          bin/git-fleximod update doc-builder
+          bin/git-fleximod update -o
+
       - name: Set image tag for docs build
         id: set-image-tag
         run: |
           echo "IMAGE_TAG=$(echo '${{ steps.meta.outputs.tags }}' | head -n 1 | cut -d',' -f1)" >> $GITHUB_ENV
+
       - name: Build docs using Docker (Podman has trouble on GitHub runners)
         id: build-docs
         run: |

.github/workflows/docs-build-and-deploy.yml

@@ -6,12 +6,14 @@ on:
     branches: ['master', 'release-clm5.0']
     paths:
       - 'doc/**'
+      - '!doc/test/*'
       - '!doc/*ChangeLog*'
       - '!doc/*ChangeSum*'
       - '!doc/UpdateChangelog.pl'
       # Include all include::ed files outside doc/ directory!
       - 'src/README.unit_testing'
       - 'tools/README'
+      - 'doc/test/test_container_eq_ctsm_pylib.sh'
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
@@ -46,10 +48,14 @@ jobs:
       - name: Setup Pages
         uses: actions/configure-pages@v5
 
+      # Check out all submodules because we might :literalinclude: something from one
+      - name: Checkout all submodules
+        run: |
+          bin/git-fleximod update -o
+
       - name: Build docs using container
         id: build-docs
         run: |
-          bin/git-fleximod update -o
           cd doc
           ./build_docs_to_publish -d --site-root https://escomp.github.io/CTSM
 

.github/workflows/docs-common.yml

@@ -26,9 +26,10 @@ jobs:
           fetch-depth: 0
           lfs: true
 
-      - name: Checkout doc-builder external
+      # Check out all submodules because we might :literalinclude: something from one
+      - name: Checkout all submodules
         run: |
-          bin/git-fleximod update doc-builder
+          bin/git-fleximod update -o
 
       # Do this if not using conda
       # Based on  https://github.com/actions/cache/blob/main/examples.md#python---pip

.github/workflows/docs-omnibus.yml

@@ -5,39 +5,34 @@ on:
     # Run when a change to these files is pushed to any branch. Without the "branches:" line, for some reason this will be run whenever a tag is pushed, even if the listed files aren't changed.
     branches: ['*']
     paths:
-      - 'doc/**'
-      - '!doc/*ChangeLog*'
-      - '!doc/*ChangeSum*'
-      - '!doc/UpdateChangelog.pl'
-      # Include all include::ed files outside doc/ directory!
-      - 'src/README.unit_testing'
-      - 'tools/README'
+      - 'doc/test/*'
+      - 'doc/Makefile'
 
   pull_request:
     # Run on pull requests that change the listed files
     paths:
-      - 'doc/**'
-      - '!doc/*ChangeLog*'
-      - '!doc/*ChangeSum*'
-      - '!doc/UpdateChangelog.pl'
-      # Include all include::ed files outside doc/ directory!
-      - 'src/README.unit_testing'
-      - 'tools/README'
+      - 'doc/test/*'
+      - 'doc/Makefile'
 
   workflow_dispatch:
 
 jobs:
   build-docs-omnibus-test:
+    # Don't run on forks, because part(s) of omnibus testing script will look for
+    # branch(es) that forks may not have.
+    if: ${{ github.repository == 'ESCOMP/CTSM' }}
+
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
           lfs: true
 
-      - name: Checkout doc-builder external
+      # Check out all submodules because we might :literalinclude: something from one
+      - name: Checkout all submodules
         run: |
-          bin/git-fleximod update doc-builder
+          bin/git-fleximod update -o
 
       # Set up conda
       - name: Set up conda environment
@@ -48,7 +43,6 @@ jobs:
           channels: conda-forge
           auto-activate-base: false
 
-      # TODO: Split testing.sh tests into their own steps in this job
       - name: Text Sphinx builds with omnibus script
         run: |
-          cd doc && ./testing.sh
+          cd doc/test/ && ./testing.sh

.github/workflows/docs-ctsm_pylib.yml → .github/workflows/docs-update-ctsm_pylib.yml

@@ -1,18 +1,22 @@
-name: Test building docs with ctsm_pylib
+name: Docs tests to run when ctsm_pylib is updated
 
 on:
   push:
     # Run when a change to these files is pushed to any branch. Without the "branches:" line, for some reason this will be run whenever a tag is pushed, even if the listed files aren't changed.
     branches: ['*']
     paths:
       - 'python/conda_env_ctsm_py.txt'
+      - 'doc/ctsm-docs_container/requirements.txt'
       - '.github/workflows/docs-common.yml'
+      - '.github/workflows/docs-update-dependency-common.yml'
 
   pull_request:
     # Run on pull requests that change the listed files
     paths:
       - 'python/conda_env_ctsm_py.txt'
+      - 'doc/ctsm-docs_container/requirements.txt'
       - '.github/workflows/docs-common.yml'
+      - '.github/workflows/docs-update-dependency-common.yml'
 
   schedule:
     # 8 am every Monday UTC
@@ -25,14 +29,23 @@ permissions:
 jobs:
   test-build-docs-ctsm_pylib:
     if: ${{ always() }}
-    name: With ctsm_pylib
+    name: Build with ctsm_pylib
     uses: ./.github/workflows/docs-common.yml
     with:
       use_conda: true
       conda_env_file: python/conda_env_ctsm_py.yml
       conda_env_name: ctsm_pylib
 
-  # File an issue if the docs build failed during a scheduled run
+  test-update-dependency:
+    if: ${{ always() }}
+    name: Docs dependency update tests
+    uses: ./.github/workflows/docs-update-dependency-common.yml
+
+  # File an issue if the docs build failed during a scheduled run.
+  # The main thing we're concerned about in that case is something having
+  # changed outside the repository that's causing the ctsm_pylib setup to
+  # fail. Thus, we don't need this job to wait for BOTH the above jobs---
+  # if one fails, they both will.
   file-issue-on-failure:
     if: |
       failure() &&

.github/workflows/docs-update-dependency-common.yml

@@ -0,0 +1,77 @@
+name: Jobs shared by docs workflows that run when a dependency is updated
+
+on:
+  workflow_call:
+    inputs:
+      # Conda is always needed for both jobs in this workflow. Here,
+      # we set default values for the variables in case the calling
+      # workflow doesn't provide them.
+      conda_env_file:
+        required: false
+        type: string
+        default: "python/conda_env_ctsm_py.yml"
+      conda_env_name:
+        required: false
+        type: string
+        default: "ctsm_pylib"
+    secrets: {}
+
+jobs:
+  compare-docbuilder-vs-ctsmpylib:
+    name: Are both methods identical?
+
+    # Don't run on forks, because test_container_eq_ctsm_pylib.sh uses
+    # build_docs_to_publish, which will look for branch(es) that forks
+    # may not have
+    if: ${{ github.repository == 'ESCOMP/CTSM' }}
+
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          lfs: true
+
+      # Check out all submodules because we might :literalinclude: something from one
+      - name: Checkout all submodules
+        run: |
+          bin/git-fleximod update -o
+
+      - name: Set up conda environment
+        uses: conda-incubator/setup-miniconda@v3
+        with:
+          activate-environment: ${{ inputs.conda_env_name }}
+          environment-file: ${{ inputs.conda_env_file }}
+          channels: conda-forge
+          auto-activate-base: false
+
+      - name: Compare docs built with container vs. ctsm_pylib
+        run: |
+          cd doc/test/
+          ./test_container_eq_ctsm_pylib.sh
+
+  makefile-method:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          lfs: true
+
+      # Check out all submodules because we might :literalinclude: something from one
+      - name: Checkout all submodules
+        run: |
+          bin/git-fleximod update -o
+
+      - name: Set up conda environment
+        uses: conda-incubator/setup-miniconda@v3
+        with:
+          activate-environment: ${{ inputs.conda_env_name }}
+          environment-file: ${{ inputs.conda_env_file }}
+          channels: conda-forge
+          auto-activate-base: false
+
+      - name: Check that Makefile method works
+        run: |
+          cd doc/test/
+          conda run -n ${{ inputs.conda_env_name }} --no-capture-output ./test_makefile_method.sh

.github/workflows/docs-update-doc-builder.yml

@@ -0,0 +1,43 @@
+name: Docs tests to run when doc-builder is updated
+
+on:
+  push:
+    # Run when a change to these files is pushed to any branch. Without the "branches:" line, for some reason this will be run whenever a tag is pushed, even if the listed files aren't changed.
+    branches: ['*']
+    paths:
+      - 'doc/doc-builder'
+      - '.github/workflows/docs-update-dependency-common.yml'
+
+  pull_request:
+    # Run on pull requests that change the listed files
+    paths:
+      - 'doc/doc-builder'
+      - '.github/workflows/docs-update-dependency-common.yml'
+
+  workflow_dispatch:
+
+permissions:
+  contents: read
+jobs:
+  test-update-dependency:
+
+    name: Tests to run when either docs dependency is updated
+    uses: ./.github/workflows/docs-update-dependency-common.yml
+
+  test-rv-setup:
+
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          lfs: true
+
+      # Check out all submodules because we might :literalinclude: something from one
+      - name: Checkout all submodules
+        run: |
+          bin/git-fleximod update -o
+
+      - name: build_docs rv method
+        run: |
+          cd doc/test/ && ./test_build_docs_-r-v.sh docker