From 8429dfd7e18e80ed7b5f4d4298523925c1643cf2 Mon Sep 17 00:00:00 2001 From: GnomeZworc Date: Sun, 25 Oct 2026 11:29:38 +0100 Subject: [PATCH] =?UTF-8?q?ci:=20docs:=20liens=20du=20menu=20de=20version?= =?UTF-8?q?=20relatifs=20=C3=A0=20switcher.json?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Le menu de version pointait sur /main/ à la racine du domaine : DOCS_BASE_PATH était vide alors que les pages sont servies sous /two/. Le thème colle l'URL d'une version devant le chemin de la page sans la résoudre, un chemin relatif y casserait donc selon la profondeur de la page. Les URL de switcher.json sont désormais relatives à switcher.json lui-même, et version-switcher.js les résout depuis cet emplacement une fois le menu rempli. Le site fonctionne ainsi sous n'importe quel sous-chemin, sans réglage. Le script est injecté par le workflow dans chaque version construite (sphinx-build -D) : une version figée comme 0.2.0, construite depuis le conf.py de son tag, le reçoit sans retoucher le tag. Vérifié en local avec les étapes du workflow : site servi sous /two/ et à la racine, liens du menu corrects sur une page de premier niveau et de sous-répertoire. Signed-off-by: GnomeZworc --- .forgejo/workflows/docs.yml | 24 ++++++++++-------------- docs/_static/version-switcher.js | 16 ++++++++++++++++ 2 files changed, 26 insertions(+), 14 deletions(-) create mode 100644 docs/_static/version-switcher.js diff --git a/.forgejo/workflows/docs.yml b/.forgejo/workflows/docs.yml index e8b7b07..6e6bb9a 100644 --- a/.forgejo/workflows/docs.yml +++ b/.forgejo/workflows/docs.yml @@ -22,13 +22,6 @@ jobs: env: TOKEN: ${{ secrets.RELEASE }} SITE_DIR: /tmp/site - # Préfixe de chemin sous lequel le site est servi. Vide = racine du - # domaine, ce qui couvre le cas courant et un serveur de test local. - # À renseigner (par exemple /two) seulement si les pages sont publiées - # sous un sous-chemin. Aucun nom d'hôte ici : les liens du menu de - # version sont relatifs à l'origine, donc le site fonctionne à - # l'identique en local et en production. - DOCS_BASE_PATH: '' steps: # fetch-depth: 0 — les tags et leur contenu sont nécessaires : chaque # version est construite depuis son propre ref. @@ -68,12 +61,16 @@ jobs: # 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. + # Le script du menu de version est pris dans l'arbre de main et injecté + # dans chaque version : une version figée le reçoit sans retoucher son tag. - name: Construire chaque version run: | build () { local ref="$1" src="$2" DOCS_VERSION="${ref}" \ /tmp/venv/bin/sphinx-build -b html -W --keep-going \ + -D html_static_path="${GITHUB_WORKSPACE}/docs/_static" \ + -D html_js_files=version-switcher.js \ -d "/tmp/doctrees-${ref}" "${src}/docs" "${SITE_DIR}/${ref}" } @@ -93,11 +90,10 @@ jobs: git worktree remove --force "/tmp/src-${version}" done - # Les liens du menu de version sont relatifs à l'origine : le thème les - # concatène au chemin de la page courante avant de les poser en href, si - # bien qu'un chemin relatif y serait résolu depuis la page et casserait - # selon sa profondeur. Une barre initiale les ancre à la racine du site, - # sans jamais nommer d'hôte. + # Les liens du menu de version sont relatifs à switcher.json, posé à la + # racine du site : version-switcher.js les résout depuis + # cet emplacement. Ni hôte ni sous-chemin ici, le site fonctionne donc + # à l'identique sous /two/, à la racine d'un domaine ou en local. - name: Assembler la racine du site run: | preferred="$(echo ${VERSIONS} | tr ' ' '\n' | head -1)" @@ -105,14 +101,14 @@ jobs: { echo '[' - echo ' {"name": "dev (main)", "version": "main", "url": "'"${DOCS_BASE_PATH}"'/main/"},' + echo ' {"name": "dev (main)", "version": "main", "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_PATH}"'/'"${version}"'/"'"${suffix}"'},' + echo ' {"name": "'"${version}"'", "version": "'"${version}"'", "url": "'"${version}"'/"'"${suffix}"'},' done } | sed '$ s/,$//' > "${SITE_DIR}/switcher.json" echo ']' >> "${SITE_DIR}/switcher.json" diff --git a/docs/_static/version-switcher.js b/docs/_static/version-switcher.js new file mode 100644 index 0000000..1454b4c --- /dev/null +++ b/docs/_static/version-switcher.js @@ -0,0 +1,16 @@ +(() => { + const versionRoot = new URL(document.documentElement.dataset.content_root, window.location.href); + const switcherUrl = new URL(DOCUMENTATION_OPTIONS.theme_switcher_json_url, versionRoot); + + const resolveLinks = (root) => { + root.querySelectorAll(".version-switcher__menu a[href]").forEach((anchor) => { + anchor.href = new URL(anchor.getAttribute("href"), switcherUrl).href; + }); + }; + + resolveLinks(document); + new MutationObserver(() => resolveLinks(document)).observe(document.documentElement, { + childList: true, + subtree: true, + }); +})();