diff --git a/.forgejo/workflows/docs.yml b/.forgejo/workflows/docs.yml index 42c201e..a07f10d 100644 --- a/.forgejo/workflows/docs.yml +++ b/.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: - - 'docs/**' - - 'release_notes/**' - - '.forgejo/workflows/docs.yml' + tags: + - '[0-9]*.[0-9]*.[0-9]*' 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. +# Deux publications simultanées se pousseraient l'une sur l'autre. 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 - # 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 + # Les versions publiables : main, plus les tags finaux qui contiennent + # déjà un répertoire docs/. 0.1.0 est antérieure à la documentation et + # n'est donc pas constructible — le filtre l'écarte de lui-même, sans + # liste à maintenir. + - name: Choisir les versions à publier run: | - /tmp/venv/bin/sphinx-build -b html -W --keep-going \ - -d /tmp/doctrees docs "${SITE_DIR}" + versions="" + 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" < + + + + two — documentation + + + +

Documentation de two

+ + 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" - # Neutralise Jekyll si le serveur de pages l'applique : Sphinx écrit - # _static/ et _sources/, que Jekyll ignore silencieusement. + find "${SITE_DIR}" -name '.buildinfo' -delete 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 diff --git a/docs/conf.py b/docs/conf.py index 34656c4..995b4dd 100644 --- a/docs/conf.py +++ b/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', + ] + }