Clean up docs workflows

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

@@ -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/testing/*'
       - '!doc/*ChangeLog*'
       - '!doc/*ChangeSum*'
       - '!doc/UpdateChangelog.pl'
       # Include all include::ed files outside doc/ directory!
       - 'src/README.unit_testing'
       - 'tools/README'
+      - 'doc/testing/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/testing/*'
+      - '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/testing/*'
+      - '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/testing && ./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: Tests for when either docs dependency is updated
+    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,75 @@
+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:
+    # 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/testing
+          ./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/testing
+          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/testing && ./test_build_docs_-r-v.sh docker

.github/workflows/docs.yml

@@ -7,25 +7,29 @@ on:
     branches: ['*']
     paths:
       - 'doc/**'
+      - '!doc/testing/*'
       - '!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/testing/test_container_eq_ctsm_pylib.sh'
 
   pull_request:
     # Run on pull requests that change the listed files
     paths:
       - 'doc/**'
+      - '!doc/testing/*'
       - '!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/testing/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

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"

doc/source/users_guide/working-with-documentation/building-docs-multiple-versions.rst

@@ -7,7 +7,7 @@ There is a menu in the lower left of the webpage that lets readers switch betwee
 
 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
+.. literalinclude:: ../../../testing/test_container_eq_ctsm_pylib.sh
    :start-at: ./build_docs_to_publish
    :end-before: VERSION LINKS WILL NOT RESOLVE
    :append: CMD _publish/index.html  # where CMD is open for Mac or wslview for Windows (Ubuntu VM)