Merge pull request #177 from microbiomedata/176-decouple-build-and-pu…

…blish-jobs-into-different-gha-workflows-to-enable-granular-reuse

Refactor GHA workflows so build steps are decoupled from deployment step

.github/workflows/assemble-website.yml

@@ -0,0 +1,63 @@
+# This GitHub Actions workflow creates a file tree consisting of several smaller file trees and a few additional files.
+# Reference: https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions
+name: Assemble website
+
+on:
+  workflow_dispatch: { }
+  # Allow this workflow to be called by other workflows.
+  # Reference: https://docs.github.com/en/actions/using-workflows/reusing-workflows
+  workflow_call: { }
+
+jobs:
+  # Use existing workflows to compile the home, Runtime, and workflow documentation.
+  # Reference: https://docs.github.com/en/actions/using-workflows/reusing-workflows#calling-a-reusable-workflow
+  compile-home-docs:
+    name: Compile home docs
+    uses: ./.github/workflows/compile-home-docs.yml
+  fetch-and-compile-runtime-docs:
+    name: Fetch and compile Runtime docs
+    uses: ./.github/workflows/fetch-and-compile-runtime-docs.yml
+  fetch-and-compile-workflow-docs:
+    name: Fetch and compile workflow docs
+    uses: ./.github/workflows/fetch-and-compile-workflow-docs.yml
+
+  assemble:
+    name: Assemble website file tree
+    # This job depends upon other jobs succeeding.
+    # Reference: https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idneeds
+    needs:
+      - compile-home-docs
+      - fetch-and-compile-runtime-docs
+      - fetch-and-compile-workflow-docs
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Check out commit  # Docs: https://github.com/actions/checkout
+        uses: actions/checkout@v4
+      - name: Download all artifacts
+        uses: actions/download-artifact@v4  # Docs: https://github.com/actions/download-artifact
+        with: { path: artifacts }
+      # Note: We use the `-T` option of the `cp` command so that the source directory name does not
+      #       get appended to the destination directory name. It's short for `--no-target-directory`.
+      #       Reference: https://www.gnu.org/software/coreutils/manual/html_node/Target-directory.html
+      - name: Assemble website file tree
+        run: |
+          mkdir -p \
+            _build/html/runtime \
+            _build/html/workflows
+          cp -R -T artifacts/home-docs-as-html        _build/html
+          cp -R -T artifacts/runtime-docs-as-html     _build/html/runtime
+          cp -R -T artifacts/workflow-docs-as-html    _build/html/workflows
+      - name: Inject robots.txt file into assembled website file tree
+        run: |
+          cp content/robots.txt _build/html/robots.txt
+          ls -R _build/html
+      - name: Save the result for publishing to GitHub Pages  # Docs: https://github.com/actions/upload-pages-artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: _build/html
+          # Note: The artifact name is "github-pages" by default; so, this specification is redundant. We include it
+          #       anyway, here, as a reminder for people that will be implementing workflows that consume the same
+          #       artifact; e.g., spell checkers and link checkers.
+          name: github-pages

.github/workflows/compile-home-docs.yml

@@ -4,6 +4,9 @@ name: Compile home documentation into HTML
 
 on:
   push: { branches: [ main ] }
+  # Run this workflow whenever someone opens or adds commits to a PR whose base branch is `main`.
+  # Reference: https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request
+  pull_request: { branches: [main] }
   workflow_dispatch: { }
   # Allow this workflow to be called by other workflows.
   # Reference: https://docs.github.com/en/actions/using-workflows/reusing-workflows

.github/workflows/deploy-to-gh-pages.yml

@@ -1,6 +1,6 @@
-# This GitHub Actions workflow creates a production build of the website and deploys it to GitHub Pages.
+# This GitHub Actions workflow deploys the website file tree to GitHub Pages.
 # Reference: https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions
-name: Build and deploy to GitHub Pages
+name: Deploy to GitHub Pages
 
 on:
   push: { branches: [ main ] }
@@ -12,60 +12,16 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  # Use existing workflows to compile the home, Runtime, and workflow documentation.
+  # Use an existing workflow to assemble the website file tree that, in this workflow, we will deploy to GitHub Pages.
   # Reference: https://docs.github.com/en/actions/using-workflows/reusing-workflows#calling-a-reusable-workflow
-  compile-home-docs:
-    name: Compile home docs
-    uses: ./.github/workflows/compile-home-docs.yml
-  fetch-and-compile-runtime-docs:
-    name: Fetch and compile Runtime docs
-    uses: ./.github/workflows/fetch-and-compile-runtime-docs.yml
-  fetch-and-compile-workflow-docs:
-    name: Fetch and compile workflow docs
-    uses: ./.github/workflows/fetch-and-compile-workflow-docs.yml
-
-  build:
-    name: Compile main website
-    # This job depends upon other jobs succeeding.
-    # Reference: https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idneeds
-    needs:
-      - compile-home-docs
-      - fetch-and-compile-runtime-docs
-      - fetch-and-compile-workflow-docs
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-    steps:
-      - name: Check out commit  # Docs: https://github.com/actions/checkout
-        uses: actions/checkout@v4
-      - name: Download all artifacts
-        uses: actions/download-artifact@v4  # Docs: https://github.com/actions/download-artifact
-        with:
-          path: artifacts
-      # Note: We use the `-T` option of the `cp` command so that the source directory name does not
-      #       get appended to the destination directory name. It's short for `--no-target-directory`.
-      #       Reference: https://www.gnu.org/software/coreutils/manual/html_node/Target-directory.html
-      - name: Assemble website file tree
-        run: |
-          mkdir -p \
-            _build/html/runtime \
-            _build/html/workflows
-          cp -R -T artifacts/home-docs-as-html        _build/html
-          cp -R -T artifacts/runtime-docs-as-html     _build/html/runtime
-          cp -R -T artifacts/workflow-docs-as-html    _build/html/workflows
-      - name: Inject robots.txt file into assembled website file tree
-        run: |
-          cp content/robots.txt _build/html/robots.txt
-          ls -R _build/html
-      - name: Save the result for publishing to GitHub Pages  # Docs: https://github.com/actions/upload-pages-artifact
-        uses: actions/upload-pages-artifact@v3
-        with:
-          path: _build/html
+  assemble-website:
+    name: Assemble website
+    uses: ./.github/workflows/assemble-website.yml
 
   deploy:
     name: Deploy website
     needs:
-      - build
+      - assemble-website
     runs-on: ubuntu-latest
     # Reference: https://github.com/actions/deploy-pages
     permissions:
@@ -79,3 +35,8 @@ jobs:
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v4
+        with:
+          # Note: The artifact name is "github-pages" by default; so, this specification is redundant. We include it
+          #       anyway, here, as a reminder for people that will be implementing workflows that consume the same
+          #       artifact; e.g., spell checkers and link checkers.
+          artifact_name: github-pages

.github/workflows/fetch-and-compile-runtime-docs.yml

@@ -1,7 +1,6 @@
 name: Fetch and compile Runtime docs
 
 on:
-  push: { branches: [ main ] }
   workflow_dispatch: { }
   # Allow this workflow to be called by other workflows.
   # Reference: https://docs.github.com/en/actions/using-workflows/reusing-workflows

.github/workflows/fetch-and-compile-workflow-docs.yml

@@ -1,7 +1,6 @@
 name: Fetch and compile workflow docs
 
 on:
-  push: { branches: [ main ] }
   workflow_dispatch: { }
   # Allow this workflow to be called by other workflows.
   # Reference: https://docs.github.com/en/actions/using-workflows/reusing-workflows