[mod] CI move build of online docs to dedicated workflow documentation.yml (#4733)

documentation.yml will run after integration.yml COMPLETES successfully (will
defer anything depending on integration.yml until heavy loads like container
building are moved to separate workflows) and in master branch.

Style changes, cleanup and improved integration with CI by leveraging the use of
shared cache between all workflows (not functional until all workflows have been
refactored).

1 files changed, 67 insertions, 0 deletions

diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
new file mode 100644
index 000000000..6d9f2cac5
--- /dev/null
+++ b/.github/workflows/documentation.yml
@@ -0,0 +1,67 @@
+---
+name: Documentation
+
+# yamllint disable-line rule:truthy
+on:
+  workflow_dispatch:
+  workflow_run:
+    workflows:
+      - Integration
+    types:
+      - completed
+    branches:
+      - master
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref_name }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+env:
+  PYTHON_VERSION: "3.13"
+
+jobs:
+  release:
+    if: github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success'
+    name: Release
+    runs-on: ubuntu-24.04-arm
+    permissions:
+      # for JamesIves/github-pages-deploy-action to push
+      contents: write
+
+    steps:
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "${{ env.PYTHON_VERSION }}"
+
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: "false"
+          fetch-depth: "0"
+
+      - name: Setup cache Python
+        uses: actions/cache@v4
+        with:
+          key: "python-${{ env.PYTHON_VERSION }}-${{ runner.arch }}-${{ hashFiles('./requirements*.txt') }}"
+          restore-keys: "python-${{ env.PYTHON_VERSION }}-${{ runner.arch }}-"
+          path: "./local/"
+
+      - name: Setup venv
+        run: make V=1 install
+
+      - name: Build documentation
+        run: make V=1 docs.clean docs.html
+
+      - name: Release
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: "dist/docs"
+          branch: "gh-pages"
+          commit-message: "[doc] build from commit ${{ github.sha }}"
+          # Automatically remove deleted files from the deploy branch
+          clean: "true"
+          single-commit: "true"