Merge b4bdev 20250625

.git-blame-ignore-revs

@@ -67,3 +67,5 @@ cdf40d265cc82775607a1bf25f5f527bacc97405
 3b7a2876933263f8986e4069f5d23bd45635756f
 3dd489af7ebe06566e2c6a1c7ade18550f1eb4ba
 742cfa606039ab89602fde5fef46458516f56fd4
+4ad46f46de7dde753b4653c15f05326f55116b73
+75db098206b064b8b7b2a0604d3f0bf8fdb950cc

.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

.github/workflows/docs.yml

@@ -7,25 +7,29 @@ on:
     branches: ['*']
     paths:
       - 'doc/**'
+      - '!doc/test/*'
       - '!doc/*ChangeLog*'
       - '!doc/*ChangeSum*'
       - '!doc/UpdateChangelog.pl'
       - '.github/workflows/docs-common.yml'
       # Include all include::ed files outside doc/ directory!
       - 'src/README.unit_testing'
       - 'tools/README'
+      - 'doc/test/test_container_eq_ctsm_pylib.sh'
 
   pull_request:
     # Run on pull requests that change the listed files
     paths:
       - 'doc/**'
+      - '!doc/test/*'
       - '!doc/*ChangeLog*'
       - '!doc/*ChangeSum*'
       - '!doc/UpdateChangelog.pl'
       - '.github/workflows/docs-common.yml'
       # Include all include::ed files outside doc/ directory!
       - 'src/README.unit_testing'
       - 'tools/README'
+      - 'doc/test/test_container_eq_ctsm_pylib.sh'
 
   workflow_dispatch:
 
@@ -49,9 +53,10 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      - 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: Build docs using Docker (Podman has trouble on GitHub runners)
         id: build-docs

bld/CLMBuildNamelist.pm

@@ -4478,6 +4478,10 @@ sub setup_logic_cngeneral {
                   "(eg. don't use these options with SP mode).");
     }
   }
+  if ( &value_is_true($nl->get_value('reseed_dead_plants')) &&
+       &remove_leading_and_trailing_quotes($nl_flags->{'clm_start_type'}) eq "branch") {
+      $log->fatal_error("reseed_dead_plants MUST be .false. in a branch run");
+  }
 }
 
 #-------------------------------------------------------------------------------

bld/unit_testers/build-namelist_test.pl

@@ -678,6 +678,10 @@ sub cat_and_create_namelistinfile {
                                      namelst=>"soil_decomp_method='None'",
                                      phys=>"clm5_0",
                                    },
+     "reseed with branch"        =>{ options=>"-clm_start_type branch -envxml_dir .",
+                                     namelst=>"reseed_dead_plants=.true.",
+                                     phys=>"clm6_0",
+                                   },
      "reseed without CN"         =>{ options=>" -envxml_dir . -bgc sp",
                                      namelst=>"reseed_dead_plants=.true.",
                                      phys=>"clm5_0",

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.2c"
+LABEL org.opencontainers.image.version="v1.0.2d"