👷 Upgrade CI for docs (#642)

.github/workflows/build-docs.yml

@@ -4,16 +4,38 @@ on:
     branches:
       - master
   pull_request:
-    types: [opened, synchronize]
-  workflow_dispatch:
-    inputs:
-      debug_enabled:
-        description: 'Run the build with tmate debugging enabled (https://github.com/marketplace/actions/debugging-with-tmate)'
-        required: false
-        default: false
+    types:
+      - opened
+      - synchronize
 jobs:
+  changes:
+    runs-on: ubuntu-latest
+    # Required permissions
+    permissions:
+      pull-requests: read
+    # Set job outputs to values from filter step
+    outputs:
+      docs: ${{ steps.filter.outputs.docs }}
+    steps:
+    - uses: actions/checkout@v3
+    # For pull requests it's not necessary to checkout the code but for the main branch it is
+    - uses: dorny/paths-filter@v2
+      id: filter
+      with:
+        filters: |
+          docs:
+            - README.md
+            - docs/**
+            - docs_src/**
+            - pyproject.toml
+            - mkdocs.yml
+            - mkdocs.insiders.yml
+
   build-docs:
-    runs-on: ubuntu-20.04
+    needs:
+      - changes
+    if: ${{ needs.changes.outputs.docs == 'true' }}
+    runs-on: ubuntu-latest
     steps:
       - name: Dump GitHub context
         env:
@@ -23,13 +45,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
-          python-version: "3.7"
-      # Allow debugging with tmate
-      - name: Setup tmate session
-        uses: mxschmitt/action-tmate@v3
-        if: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.debug_enabled }}
-        with:
-          limit-access-to-actor: true
+          python-version: "3.11"
       - uses: actions/cache@v3
         id: cache
         with:
@@ -37,36 +53,39 @@ jobs:
           key: ${{ runner.os }}-python-docs-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml') }}-v01
       - name: Install Flit
         if: steps.cache.outputs.cache-hit != 'true'
-        run: python3.7 -m pip install flit
+        run: python -m pip install flit
       - name: Install docs extras
         if: steps.cache.outputs.cache-hit != 'true'
-        run: python3.7 -m flit install --extras doc
+        run: python -m flit install --extras doc
       - name: Install Material for MkDocs Insiders
         if: ( github.event_name != 'pull_request' || github.event.pull_request.head.repo.fork == false ) && steps.cache.outputs.cache-hit != 'true'
-        run: python3.7 -m pip install git+https://${{ secrets.TYPER_MKDOCS_MATERIAL_INSIDERS }}@github.com/squidfunk/mkdocs-material-insiders.git
+        run: python -m pip install git+https://${{ secrets.TYPER_MKDOCS_MATERIAL_INSIDERS }}@github.com/squidfunk/mkdocs-material-insiders.git
       - uses: actions/cache@v3
         with:
           key: mkdocs-cards-${{ github.ref }}-v1
           path: .cache
       - name: Build Docs
         if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork == true
-        run: python3.7 -m mkdocs build
+        run: python -m mkdocs build
       - name: Build Docs with Insiders
         if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.fork == false
-        run: python3.7 -m mkdocs build --config-file mkdocs.insiders.yml
+        run: python -m mkdocs build --config-file mkdocs.insiders.yml
       - name: Zip docs
         run: bash ./scripts/zip-docs.sh
       - uses: actions/upload-artifact@v3
         with:
-          name: docs-zip
-          path: ./site/docs.zip
-      - name: Deploy to Netlify
-        uses: nwtgck/actions-netlify@v2.0.0
+          name: docs-site
+          path: ./site/**
+
+  # https://github.com/marketplace/actions/alls-green#why
+  docs-all-green:  # This job does nothing and is only used for the branch protection
+    if: always()
+    needs:
+      - build-docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Decide whether the needed jobs succeeded or failed
+        uses: re-actors/alls-green@release/v1
         with:
-          publish-dir: './site'
-          production-branch: master
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-          enable-commit-comment: false
-        env:
-          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
-          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
+          jobs: ${{ toJSON(needs) }}
+          allowed-skips: build-docs

.github/workflows/preview-docs.yml

@@ -1,4 +1,4 @@
-name: Preview Docs
+name: Deploy Docs
 on:
   workflow_run:
     workflows:
@@ -7,39 +7,42 @@ on:
       - completed
 
 jobs:
-  preview-docs:
-    runs-on: ubuntu-20.04
+  deploy-docs:
+    runs-on: ubuntu-latest
     steps:
+      - name: Dump GitHub context
+        env:
+          GITHUB_CONTEXT: ${{ toJson(github) }}
+        run: echo "$GITHUB_CONTEXT"
       - uses: actions/checkout@v3
       - name: Clean site
         run: |
           rm -rf ./site
           mkdir ./site
       - name: Download Artifact Docs
-        uses: dawidd6/action-download-artifact@v2.26.0
+        id: download
+        uses: dawidd6/action-download-artifact@v2.27.0
         with:
+          if_no_artifact_found: ignore
           github_token: ${{ secrets.GITHUB_TOKEN }}
           workflow: build-docs.yml
           run_id: ${{ github.event.workflow_run.id }}
-          name: docs-zip
+          name: docs-site
           path: ./site/
-      - name: Unzip docs
-        run: |
-          cd ./site
-          unzip docs.zip
-          rm -f docs.zip
       - name: Deploy to Netlify
+        if: steps.download.outputs.found_artifact == 'true'
         id: netlify
         uses: nwtgck/actions-netlify@v2.0.0
         with:
           publish-dir: './site'
-          production-deploy: false
+          production-deploy: ${{ github.event.workflow_run.head_repository.full_name == github.repository && github.event.workflow_run.head_branch == 'master' }}
           github-token: ${{ secrets.GITHUB_TOKEN }}
           enable-commit-comment: false
         env:
           NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
           NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
       - name: Comment Deploy
+        if: steps.netlify.outputs.deploy-url != ''
         uses: ./.github/actions/comment-docs-preview-in-pr
         with:
           token: ${{ secrets.GITHUB_TOKEN }}