tesT

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

.forgejo/workflows/docs.yml

@@ -1,17 +1,18 @@
 name: Documentation
 
+# Un tag de release ajoute une version au site : la publication est donc
+# déclenchée par les deux, sans filtre de chemin sur les tags — c'est le tag
+# lui-même qui est la nouveauté, pas un fichier modifié.
 on:
   push:
     branches:
+      - main
       - feature-46
-    paths:
+    tags:
-      - 'docs/**'
+      - '[0-9]*.[0-9]*.[0-9]*'
-      - 'release_notes/**'
-      - '.forgejo/workflows/docs.yml'
   workflow_dispatch:
 
-# Deux publications simultanées se pousseraient l'une sur l'autre : la branche
+# Deux publications simultanées se pousseraient l'une sur l'autre.
-# pages est écrasée à chaque fois, le dernier arrivé gagnerait au hasard.
 concurrency:
   group: pages
   cancel-in-progress: false
@@ -22,8 +23,16 @@ jobs:
     env:
       TOKEN: ${{ secrets.RELEASE }}
       SITE_DIR: /tmp/site
+      # URL publique du site de documentation : sert à construire les liens du
+      # sélecteur de version, qui doivent être absolus pour fonctionner depuis
+      # n'importe quelle page de n'importe quelle version.
+      DOCS_BASE_URL: https://syonad.g3e.fr/two
     steps:
+      # fetch-depth: 0 — les tags et leur contenu sont nécessaires : chaque
+      # version est construite depuis son propre ref.
       - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
 
       - name: Installer Sphinx
         run: |
@@ -33,32 +42,100 @@ jobs:
           /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
+      # Les versions publiables : main, plus les tags finaux qui contiennent
-      # publication, pas produire un site avec des liens morts. --keep-going
+      # déjà un répertoire docs/. 0.1.0 est antérieure à la documentation et
-      # affiche tous les avertissements avant d'échouer, plutôt que le premier.
+      # n'est donc pas constructible — le filtre l'écarte de lui-même, sans
-      # -d place le cache de Sphinx hors du site : sans lui, .doctrees — près
+      # liste à maintenir.
-      # d'un mégaoctet d'état interne — se retrouve publié à la racine.
+      - name: Choisir les versions à publier
-      - name: Construire la documentation
         run: |
-          /tmp/venv/bin/sphinx-build -b html -W --keep-going \
+          versions=""
-            -d /tmp/doctrees docs "${SITE_DIR}"
+          for tag in $(git tag --sort=-v:refname)
+          do
+            case "${tag}" in *rc*) continue ;; esac
+            if git ls-tree --name-only "${tag}" | grep -qx docs
+            then
+              versions="${versions} ${tag}"
+            else
+              echo "ignoré : ${tag} n'a pas de docs/"
+            fi
+          done
+          echo "VERSIONS=${versions# }" >> "${GITHUB_ENV}"
+          echo "versions retenues : main${versions}"
+
+      # main est construite en premier et son échec est fatal : la doc courante
+      # doit toujours partir. L'échec d'une version figée est signalé mais ne
+      # bloque pas la publication — une vieille version qui ne se reconstruit
+      # plus ne doit pas empêcher de publier la doc du jour.
+      - name: Construire chaque version
+        run: |
+          build () {
+            local ref="$1" src="$2"
+            DOCS_BASE_URL="${DOCS_BASE_URL}" DOCS_VERSION="${ref}" \
+              /tmp/venv/bin/sphinx-build -b html -W --keep-going \
+                -d "/tmp/doctrees-${ref}" "${src}/docs" "${SITE_DIR}/${ref}"
+          }
+
+          build main .
+
+          for version in ${VERSIONS}
+          do
+            rm -rf "/tmp/src-${version}"
+            git worktree add --quiet --detach "/tmp/src-${version}" "${version}"
+            if build "${version}" "/tmp/src-${version}"
+            then
+              echo "construit : ${version}"
+            else
+              echo "::warning::la version ${version} ne se construit plus, elle est absente du site"
+              rm -rf "${SITE_DIR}/${version}"
+            fi
+            git worktree remove --force "/tmp/src-${version}"
+          done
+
+      - name: Assembler la racine du site
+        run: |
+          # La version mise en avant est la dernière release finale, main sinon.
+          preferred="$(echo ${VERSIONS} | tr ' ' '\n' | head -1)"
+          [ -n "${preferred}" ] || preferred="main"
+
+          {
+            echo '['
+            echo '  {"name": "dev (main)", "version": "main", "url": "'"${DOCS_BASE_URL}"'/main/"},'
+            first=1
+            for version in ${VERSIONS}
+            do
+              [ -d "${SITE_DIR}/${version}" ] || continue
+              [ ${first} -eq 1 ] && suffix=', "preferred": true' || suffix=''
+              first=0
+              echo '  {"name": "'"${version}"'", "version": "'"${version}"'", "url": "'"${DOCS_BASE_URL}"'/'"${version}"'/"'"${suffix}"'},'
+            done
+          } | sed '$ s/,$//' > "${SITE_DIR}/switcher.json"
+          echo ']' >> "${SITE_DIR}/switcher.json"
+
+          python3 -c "import json,sys; json.load(open('${SITE_DIR}/switcher.json'))"
+          cat "${SITE_DIR}/switcher.json"
+
+          # La racine ne sert qu'à rediriger : le contenu vit dans les
+          # sous-répertoires de version.
+          cat > "${SITE_DIR}/index.html" <<HTML
+          <!doctype html>
+          <html lang="fr">
+          <head>
+            <meta charset="utf-8">
+            <title>two — documentation</title>
+            <meta http-equiv="refresh" content="0; url=./${preferred}/">
+            <link rel="canonical" href="${DOCS_BASE_URL}/${preferred}/">
+          </head>
+          <body><p><a href="./${preferred}/">Documentation de two</a></p></body>
+          </html>
+          HTML
 
       - 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"
+          find "${SITE_DIR}" -name '.buildinfo' -delete
-          # 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. Le build est
-      # greffé sur l'historique existant plutôt que poussé en force : un push
-      # en avance rapide ne demande que le droit d'écrire sur la branche, là
-      # où le force-push exige une dérogation supplémentaire dans la
-      # protection de branche.
       - name: Publier sur la branche pages
         run: |
           cd "${SITE_DIR}"
@@ -67,8 +144,6 @@ jobs:
           git config user.email "forgejo-actions@git.g3e.fr"
           git remote add origin "https://${TOKEN}@git.g3e.fr/${{ github.repository }}.git"
 
-          # --depth=1 : seul le dernier commit sert de parent, l'historique
-          # complet du site n'a pas à être rapatrié à chaque build.
           if git fetch --quiet --depth=1 origin pages 2>/dev/null
           then
             git reset --soft FETCH_HEAD

docs/conf.py

@@ -3,6 +3,8 @@
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+import os
+
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
@@ -49,6 +51,12 @@ html_show_sphinx = False
 html_copy_source = False
 html_show_sourcelink = False
 
+# Le sélecteur de version est piloté par le workflow de publication : hors CI
+# ces variables sont absentes, le sélecteur n'apparaît pas, et le build ne
+# dépend d'aucun réseau.
+_docs_base_url = os.environ.get('DOCS_BASE_URL')
+_docs_version = os.environ.get('DOCS_VERSION')
+
 html_theme_options = {
     'home_page_in_toc': True,
     'use_download_button': False,
@@ -61,3 +69,20 @@ html_theme_options = {
         },
     ],
 }
+
+if _docs_base_url and _docs_version:
+    html_theme_options['switcher'] = {
+        'json_url': f'{_docs_base_url}/switcher.json',
+        'version_match': _docs_version,
+    }
+    # Le thème book vide navbar_start et place tout dans la barre latérale : le
+    # sélecteur doit donc y être inséré explicitement, à côté du logo.
+    html_sidebars = {
+        '**': [
+            'navbar-logo.html',
+            'icon-links.html',
+            'version-switcher.html',
+            'search-button-field.html',
+            'sbt-sidebar-nav.html',
+        ]
+    }