ci: build and publish the documentation to the pages branch

Signed-off-by: GnomeZworc <nicolas.boufidjeline@g3e.fr>

.forgejo/workflows/docs.yml

@@ -0,0 +1,70 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - feature-46
+    paths:
+      - 'docs/**'
+      - 'release_notes/**'
+      - '.forgejo/workflows/docs.yml'
+  workflow_dispatch:
+
+# Deux publications simultanées se pousseraient l'une sur l'autre : la branche
+# pages est écrasée à chaque fois, le dernier arrivé gagnerait au hasard.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    runs-on: docker
+    env:
+      TOKEN: ${{ secrets.RELEASE }}
+      SITE_DIR: /tmp/site
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Installer Sphinx
+        run: |
+          apt-get update
+          apt-get install -y python3 python3-venv git
+          python3 -m venv /tmp/venv
+          /tmp/venv/bin/pip install --quiet --upgrade pip
+          /tmp/venv/bin/pip install --quiet -r docs/requirements.txt
+
+      # -W --keep-going : une référence croisée cassée doit arrêter la
+      # publication, pas produire un site avec des liens morts. --keep-going
+      # affiche tous les avertissements avant d'échouer, plutôt que le premier.
+      # -d place le cache de Sphinx hors du site : sans lui, .doctrees — près
+      # d'un mégaoctet d'état interne — se retrouve publié à la racine.
+      - name: Construire la documentation
+        run: |
+          /tmp/venv/bin/sphinx-build -b html -W --keep-going \
+            -d /tmp/doctrees docs "${SITE_DIR}"
+
+      - name: Alléger le site
+        run: |
+          # Source maps du thème : ~3 Mo de fichiers que seuls les outils de
+          # développement du navigateur vont chercher, jamais une page servie.
+          find "${SITE_DIR}" -name '*.map' -delete
+          rm -f "${SITE_DIR}/.buildinfo"
+          # Neutralise Jekyll si le serveur de pages l'applique : Sphinx écrit
+          # _static/ et _sources/, que Jekyll ignore silencieusement.
+          touch "${SITE_DIR}/.nojekyll"
+          du -sh "${SITE_DIR}"
+
+      # La branche pages ne contient que le site, à la racine, en un seul
+      # commit sans histoire : ce sont des artefacts reconstructibles, et
+      # l'historique de main suffit à savoir d'où ils viennent.
+      - name: Publier sur la branche pages
+        run: |
+          cd "${SITE_DIR}"
+          git init --quiet --initial-branch=pages
+          git config user.name "forgejo-actions"
+          git config user.email "forgejo-actions@git.g3e.fr"
+          git add -A
+          git commit --quiet -m "docs: build de ${GITHUB_SHA}"
+          git push --force --quiet \
+            "https://${TOKEN}@git.g3e.fr/${{ github.repository }}.git" pages
+          echo "publié : $(git rev-parse --short HEAD) — $(git ls-files | wc -l) fichiers"

.gitignore

@@ -30,3 +30,6 @@ go.work.sum
 
 # ignore local info
 data/
+
+# Sphinx build output
+docs/_build/