Deploy docs dependency management

.github/workflows/deploy-docs.yml

@@ -1,15 +1,18 @@
 name: Deploy documentation
 
 on:
-  # Only trigger on pushes to master
-  push:
+  # (A) Wait until the "Build documentation" workflow completes,
+  #     but ONLY if the branch is master
+  workflow_run:
+    workflows: ["Build documentation"]   # Must match the 'name:' in build-docs.yml
     branches: [ "master" ]
+    types: [ completed ]
 
-  # Optionally trigger on releases (created/published)
+  # (B) Also trigger if a new release is created or published
   release:
     types: [created, published]
 
-  # Allow manual triggering
+  # (C) Or trigger manually
   workflow_dispatch:
 
 permissions:
@@ -23,26 +26,40 @@ concurrency:
 
 jobs:
   deploy-docs:
+    # Run only if:
+    # - This was triggered by a 'workflow_run' event
+    #   (which must have concluded successfully AND was a push event),
+    #   OR
+    # - This was triggered by a release event,
+    #   OR
+    # - This was triggered by a manual workflow_dispatch.
+    if: >
+      (github.event_name == 'workflow_run' &&
+       github.event.workflow_run.conclusion == 'success' &&
+       github.event.workflow_run.event == 'push') ||
+      github.event_name == 'release' ||
+      github.event_name == 'workflow_dispatch'
+
+    runs-on: ubuntu-latest
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
 
     steps:
       - name: Download docs artifact
         uses: actions/download-artifact@v3
         with:
           name: docs-artifact
+          path: docs_html  # Extract to a known subdirectory
 
       - name: Setup Pages
         uses: actions/configure-pages@v5
 
-      - name: Upload artifact
+      - name: Upload artifact to GH Pages
         uses: actions/upload-pages-artifact@v3
         with:
-          # Adjust to the path where your built documentation resides
-          path: './docs/_build/html'
+          path: docs_html
 
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v4