From 57e29e6f29dfcf449f28a943204bcafc804cd21a Mon Sep 17 00:00:00 2001
From: glopesdev <g.lopes@neurogears.org>
Date: Mon, 24 Aug 2026 02:55:44 +0100
Subject: [PATCH] Publish documentation as a GitHub Pages artifact

The documentation job no longer pushes the built site to a gh-pages
branch with mkdocs gh-deploy. It now runs mkdocs build and uploads the
result with actions/upload-pages-artifact, and a new publish job
deploys that artifact with actions/deploy-pages from a
documentation-website environment.

Building now runs on every push and pull request, so a broken mkdocs
configuration fails a pull request instead of only failing when a
release is published. Publishing still requires a published release
that is not a prerelease, and can also be requested with the
publish-docs-website workflow dispatch input.
---
 .github/workflows/harp.yml | 46 +++++++++++++++++++++++++++++---------
 1 file changed, 36 insertions(+), 10 deletions(-)

diff --git a/.github/workflows/harp.yml b/.github/workflows/harp.yml
index 74ad5a5..4c876d0 100644
--- a/.github/workflows/harp.yml
+++ b/.github/workflows/harp.yml
@@ -8,6 +8,10 @@ on:
     release:
         types: [published]
     workflow_dispatch:
+        inputs:
+            publish-docs-website:
+                description: "Publish docs website to GitHub Pages?"
+                default: "false"
 
 jobs:
     # ---- Tests ----
@@ -115,12 +119,10 @@ jobs:
               with:
                   files: dist/*
 
-    # ---- Docs ----
+    # ---- Build docs ----
     build-docs:
-        name: Build and deploy documentation to GitHub Pages
+        name: Build documentation
         runs-on: ubuntu-latest
-        needs: build-release
-        if: github.event_name == 'release' && !github.event.release.prerelease
         steps:
             - name: Checkout
               uses: actions/checkout@v7
@@ -135,10 +137,34 @@ jobs:
             - name: Install dependencies
               run: uv sync --group docs
 
-            - name: Configure Git user
-              run: |
-                  git config user.name "github-actions[bot]"
-                  git config user.email "github-actions[bot]@users.noreply.github.com"
+            - name: Build documentation
+              run: uv run mkdocs build
+
+            - name: Collect documentation website artifact
+              uses: actions/upload-pages-artifact@v5
+              with:
+                  path: site/
 
-            - name: Build & Deploy docs
-              run: uv run mkdocs gh-deploy --force
+    # ---- Publish docs ----
+    publish-docs:
+        name: Publish documentation to GitHub Pages
+        runs-on: ubuntu-latest
+        needs: [build-docs, publish-to-pypi]
+        permissions:
+            # Both required by actions/deploy-pages.
+            pages: write
+            id-token: write
+        environment:
+            name: documentation-website
+            url: ${{ steps.publish.outputs.page_url }}
+        if: |
+            !cancelled() && !failure() && needs.build-docs.result == 'success'
+            && (
+              (github.event_name == 'release' && !github.event.release.prerelease)
+              || (github.event_name == 'workflow_dispatch' && github.event.inputs.publish-docs-website == 'true')
+              || (github.event_name == 'push' && vars.CONTINUOUS_DOCUMENTATION)
+            )
+        steps:
+            - name: Publish to GitHub Pages
+              id: publish
+              uses: actions/deploy-pages@v5