Merge pull request #146 from geotribu/docs/update-to-github-actions-w…

…orkflow

docs: use modern GitHub Actions based workflow

.github/workflows/documentation.yml

@@ -2,21 +2,43 @@ name: "📚 Documentation"
 
 on:
   push:
-    branches: [main]
+    branches:
+      - main
     paths:
       - ".github/workflows/documentation.yml"
-      - "docs/**/*"
+      - "docs/*/**"
       - "qtribu/**/*.py"
       - "qtribu/metadata.txt"
       - "requirements/documentation.txt"
     tags:
       - "*"
 
+  pull_request:
+    branches:
+      - main
+    paths:
+      - ".github/workflows/documentation.yml"
+      - docs/**/*
+      - requirements/documentation.txt
+
+  workflow_dispatch:
+
+# Allow one concurrent deployment per branch/pr
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
 env:
   PYTHON_VERSION: 3.9
 
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
 jobs:
-  build-docs:
+  build:
     runs-on: ubuntu-latest
 
     steps:
@@ -30,23 +52,33 @@ jobs:
           cache-dependency-path: "requirements/documentation.txt"
           python-version: ${{ env.PYTHON_VERSION }}
 
-      - name: Cache Sphinx cache
-        uses: actions/cache@v3
-        with:
-          path: docs/_build/cache
-          key: ${{ runner.os }}-sphinx-${{ hashFiles('docs/**/*') }}
-          restore-keys: |
-            ${{ runner.os }}-sphinx-
-
-      - name: Install project requirements
+      - name: Install dependencies
         run: |
-          python -m pip install -U pip setuptools wheel
+          python -m pip install --upgrade pip setuptools wheel
           python -m pip install -U -r requirements/documentation.txt
 
       - name: Build doc using Sphinx
-        run: sphinx-build -b html -d docs/_build/cache -j auto -q docs docs/_build/html
+        run: sphinx-build -b html -d docs/_build/cache -j auto docs docs/_build/html
+
+      - name: Save build doc as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: documentation
+          path: docs/_build/html/*
+          if-no-files-found: error
+          retention-days: 30
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+        if: github.event_name == 'push' && (startsWith(github.ref, 'refs/tags/') || github.ref == 'refs/heads/main')
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        if: github.event_name == 'push' && (startsWith(github.ref, 'refs/tags/') || github.ref == 'refs/heads/main')
+        with:
+          path: docs/_build/html/
 
       - name: Deploy to GitHub Pages
-        run: |
-          python -m pip install -U ghp-import
-          ghp-import --force --no-history --no-jekyll --push docs/_build/html
+        id: deployment
+        if: github.event_name == 'push' && (startsWith(github.ref, 'refs/tags/') || github.ref == 'refs/heads/main')
+        uses: actions/deploy-pages@v4

requirements/documentation.txt

@@ -1,9 +1,9 @@
 # Documentation (for devs)
 # -----------------------
 
-myst-parser[linkify]>=0.14,<2.1
-sphinx-autobuild==2021.3.14
-sphinx-autodoc-typehints>=1.11,<1.26
-sphinx-copybutton>=0.2,<1
+myst-parser[linkify]>=2
+sphinx-autobuild>=2021.*
+sphinx-autodoc-typehints>=1.25
+sphinx-copybutton>=0.5,<1
+sphinxext-opengraph>=0.7
 sphinx-rtd-theme>=1,<3
-sphinxext-opengraph>=0.4,<1