Reduce code dupe in workflows; improve workflows

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

@@ -1,25 +1,25 @@
-name: Deploy static content to Pages
+name: Build and deploy docs
 
 on:
   push:
     # Run when a change to these files is pushed to any of these branches.
-    # When you copy this into your repo, you should update this list to include all the "ref"s you
-    # put in your version_list.py.
+    # When you copy this into your repo, you should:
+    # - Replace 'master' with the name of your repo's primary branch, if it's not master (e.g.,
+    #   main)
+    # - Delete 'add-github-workflows-with-tmp-docs' 
+    # - Add any branches you refer to with DocsVersion(..., ref=*) in version_list.py
     branches: ['master', 'add-github-workflows-with-tmp-docs']
-    # When you copy this into your repo, you should uncomment the following 2 lines:
     # paths:
+    #   - '.github/workflows/docs-build-and-deploy.yml'
+    #   - '.github/workflows/docs-build_to_publish-optionally-deploy.yml'
     #   - 'doc/**'
-    # And also make sure to add any files that you "include" in your docs that live outside doc/
+    # When you copy this into your repo:
+    # - Uncomment the "paths" block above
+    # - Make sure to add any files that you "include" in your docs that live outside doc/.
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
-# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
-permissions:
-  contents: read
-  pages: write
-  id-token: write
-
 # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
 # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
 concurrency:
@@ -29,46 +29,18 @@ concurrency:
 jobs:
 
   build-and-deploy:
+    name: Call reusable workflow with deploy true
 
     # Only run on upstream repository.
     # When you copy this into your repo, replace this with yours. Case-sensitive!
     if: ${{ github.repository == 'ESMCI/doc-builder' }}
 
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
-        with:
-          # Get all history, ensuring all branches are available for checkout
-          fetch-depth: 0
-          submodules: true
-
-      - name: Setup Pages
-        uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b  # v5
-
-      # Check out all submodules because we might :literalinclude: something from one
-      - name: Checkout all submodules
-        if: ${{ hashFiles('bin/git-fleximod') != '' }}
-        run: bin/git-fleximod update -o
-
-      # When you copy this into your repo, update the --site-root URL. 
-      - name: Build docs using container
-        id: build-docs
-        run: |
-          [[ -e doc ]] && cd doc
-          ./build_docs_to_publish -d --site-root https://esmci.github.io/doc-builder --verbose
-
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@0252fc4ba7626f0298f0cf00902a25c6afc77fa8  # v3
-        with:
-          # Upload publish dir
-          # When you copy this into your repo, change this to 'doc/_publish'
-          path: '_publish'
+    # Grant the GITHUB_TOKEN the write scopes needed to deploy to GitHub Pages.
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
 
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@f33f41b675f0ab2dc5a6863c9a170fe83af3571e  # v4
+    uses: ./.github/workflows/docs-build_to_publish-optionally-deploy.yml
+    with:
+      deploy: true

.github/workflows/docs-build_to_publish-optionally-deploy.yml

@@ -0,0 +1,49 @@
+name: Test building docs "to publish" when they're updated
+
+on:
+  workflow_call:
+    inputs:
+      deploy:
+        required: false
+        type: boolean
+        default: false
+
+jobs:
+
+  build_to_publish-optionally-deploy:
+    name: Run build_to_publish and optionally deploy docs
+    runs-on: ubuntu-latest
+
+    # Only associate this job with the github-pages environment when deploying.
+    environment:
+      name: ${{ inputs.deploy && 'github-pages' || '' }}
+      url: ${{ inputs.deploy && steps.deployment.outputs.page_url || '' }}
+
+    steps:
+
+      - name: Checkout repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+        with:
+          submodules: true
+
+      - name: Build docs
+        id: build-docs
+        run: |
+          [[ -e doc ]] && cd doc
+          git fetch
+          site_root="https://${GITHUB_REPOSITORY%/*}.github.io/${GITHUB_REPOSITORY#*/}"
+          PYTHONUNBUFFERED=1 ./build_docs_to_publish -r ${PWD}/_build -d --verbose --site-root "${site_root}"
+
+      # Subsequent steps should only happen if this workflow was called with deploy true
+
+      - name: Upload artifact
+        if: ${{ inputs.deploy }}
+        uses: actions/upload-pages-artifact@0252fc4ba7626f0298f0cf00902a25c6afc77fa8  # v3
+        with:
+          # Upload publish dir
+          path: 'doc/_publish'
+
+      - name: Deploy to GitHub Pages
+        if: ${{ inputs.deploy }}
+        id: deployment
+        uses: actions/deploy-pages@f33f41b675f0ab2dc5a6863c9a170fe83af3571e  # v4

.github/workflows/docs-to-publish.yml

@@ -1,61 +1,36 @@
-name: Test building docs "to publish" when they're updated
+name: Test building docs "to publish"
 
 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: ['*']
-    # When you copy this into your repo, you should uncomment the following 3 lines:
+    # But only when these files are updated:
     # paths:
-    #   - 'doc/doc-builder'
-    #   - 'doc/build_docs_to_publish'
+    #   - '.github/workflows/docs-build-and-deploy.yml'
+    #   - '.github/workflows/docs-build_to_publish-optionally-deploy.yml'
+    #   - 'doc/**'
+    # When you copy this into your repo:
+    # - Uncomment the "paths" block above
+    # - Make sure to add any files that you "include" in your docs that live outside doc/.
 
   pull_request:
     # Run on pull requests that change the listed files
-    # When you copy this into your repo, you should uncomment the following 3 lines:
     # paths:
-    #   - 'doc/doc-builder'
-    #   - 'doc/build_docs_to_publish'
-
-  workflow_dispatch:
+    #   - '.github/workflows/docs-build-and-deploy.yml'
+    #   - '.github/workflows/docs-build_to_publish-optionally-deploy.yml'
+    #   - 'doc/**'
+    # When you copy this into your repo:
+    # - Uncomment the "paths" block above
+    # - Make sure to add any files that you "include" in your docs that live outside doc/.
 
 permissions:
   contents: read
-jobs:
-
-  test-build-docs-to-publish-container:
-    if: ${{ always() }}
-    name: With container from registry
-    runs-on: ubuntu-latest
-    steps:
 
-      - name: Checkout repository
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
-        with:
-          submodules: true
-
-      - name: Build docs using Docker (Podman has trouble on GitHub runners)
-        id: build-docs
-        run: |
-          set -o pipefail
-          mkdir -p build-logs
-          [[ -e doc ]] && cd doc
-          git fetch
-          PYTHONUNBUFFERED=1 ./build_docs_to_publish -r ${PWD}/_build -d --verbose --site-root "$PWD/_publish" 2>&1 | tee >(sed -E $'s/\x1b\\[[0-9;]*[a-zA-Z]//g' > "${GITHUB_WORKSPACE}/build-logs/build.log")
-        # The tee writes build.log for the PR comment (posted by docs-pr-failure-post-comment.yml); the inner sed strips ANSI color codes that would otherwise render as garbage in the comment.
-        # PYTHONUNBUFFERED=1 because otherwise the teed log will be out of order
-
-      # The rest of the steps only trigger on failure of above build-docs step.
-      # They upload logs that will be used by the docs-pr-failure-post-comment.yml workflow.
+jobs:
 
-      - name: Record PR number on failure
-        if: failure() && steps.build-docs.outcome == 'failure' && github.event_name == 'pull_request'
-        run: |
-          mkdir -p build-logs
-          echo "${{ github.event.pull_request.number }}" > build-logs/pr_number.txt
+  build-to-publish-dont-deploy:
+    name: Call reusable workflow with deploy false
 
-      - name: Upload logs on failure
-        if: failure() && steps.build-docs.outcome == 'failure'
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
-        with:
-          name: test-build-docs-to-publish-container_failed
-          path: build-logs/
+    uses: ./.github/workflows/docs-build_to_publish-optionally-deploy.yml
+    with:
+      deploy: false

.github/workflows/docs.yml

@@ -4,17 +4,21 @@ 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: ['*']
-    # When you copy this into your repo, you should uncomment the following 2 lines:
     # paths:
+    #   - '.github/workflows/docs.yml'
     #   - 'doc/**'
-    # And also make sure to add any files that you "include" in your docs that live outside doc/
+    # When you copy this into your repo:
+    # - Uncomment the "paths" block above.
+    # - Make sure to add any files that you "include" in your docs that live outside doc/.
 
   pull_request:
     # Run on pull requests that change the listed files
-    # When you copy this into your repo, you should uncomment the following 2 lines:
     # paths:
+    #   - '.github/workflows/docs.yml'
     #   - 'doc/**'
-    # And also make sure to add any files that you "include" in your docs that live outside doc/
+    # When you copy this into your repo:
+    # - Uncomment the "paths" block above.
+    # - Make sure to add any files that you "include" in your docs that live outside doc/.
 
   workflow_dispatch: