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-ctsm_pylib.yml

@@ -6,12 +6,14 @@ on:
     branches: ['*']
     paths:
       - 'python/conda_env_ctsm_py.txt'
+      - 'doc/ctsm-docs_container/requirements.txt'
       - '.github/workflows/docs-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'
 
   schedule:

.github/workflows/docs-omnibus.yml

@@ -5,39 +5,33 @@ 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
+    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 +42,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-update-ctsm_pylib.yml

@@ -0,0 +1,30 @@
+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'
+
+  pull_request:
+    # Run on pull requests that change the listed files
+    paths:
+      - 'python/conda_env_ctsm_py.txt'
+      - 'doc/ctsm-docs_container/requirements.txt'
+
+  workflow_dispatch:
+
+permissions:
+  contents: read
+jobs:
+  test-update-dependency:
+    # Don't run on forks
+    if: ${{ github.repository == 'ESCOMP/CTSM' }}
+
+    name: Tests to run when either docs dependency is updated
+    uses: ./.github/workflows/docs-update-dependency-common.yml
+    with:
+      conda_env_file: python/conda_env_ctsm_py.yml
+      conda_env_name: ctsm_pylib

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

@@ -0,0 +1,67 @@
+name: Jobs shared by docs workflows that run when a dependency is updated
+
+on:
+  workflow_call:
+    inputs:
+      conda_env_file:
+        required: false
+        type: string
+        default: ""
+      conda_env_name:
+        required: false
+        type: string
+        default: ""
+    secrets: {}
+
+jobs:
+  compare-docbuilder-vs-ctsmpylib:
+    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,50 @@
+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:
+    # Don't run on forks
+    if: ${{ github.repository == 'ESCOMP/CTSM' }}
+
+    name: Tests to run when either docs dependency is updated
+    uses: ./.github/workflows/docs-update-dependency-common.yml
+    with:
+      conda_env_file: python/conda_env_ctsm_py.yml
+      conda_env_name: ctsm_pylib
+
+  test-rv-setup:
+    # Don't run on forks
+    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: 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)