From 622f16954c95756cd556088ca49ec9afddf847ea Mon Sep 17 00:00:00 2001 From: skjnldsv Date: Wed, 17 Jun 2026 11:20:10 +0200 Subject: [PATCH] feat: dynamic version detection, picker labels and layout MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit All version constants (version_stable, version_start, display_version) are now injected by CI via detect-versions.php rather than hardcoded in conf.py. Branching off stable35 requires zero conf.py changes — the new branch auto-detects its version from GITHUB_REF/GITHUB_BASE_REF. sphinxbuild.yml runs PHP detection on every HTML build and exports DOCS_VERSION_STABLE, DOCS_VERSION_START and DOCS_DISPLAY_VERSION to the environment. conf.py reads them with hardcoded fallbacks for local builds. No more regex or GITHUB_BASE_REF sniffing in Python. Version picker labels are also updated: 35 (upcoming) / 34 (latest) / 33 (stable) / 32 (stable) / N (unsupported). The picker uses a 2-column grid for both the versions and languages sections, with the section emoji injected via CSS ::before so the label text and entries align cleanly. Follows up on #13404 and #15140. Signed-off-by: skjnldsv --- .github/workflows/sphinxbuild.yml | 31 +++++++-------- _shared_assets/static/custom.css | 41 ++++++++++++++++++++ admin_manual/_templates/versions.html | 6 +-- build/detect-versions.php | 3 ++ conf.py | 47 ++++++++--------------- developer_manual/_templates/versions.html | 6 +-- user_manual/_templates/versions.html | 12 +++--- 7 files changed, 87 insertions(+), 59 deletions(-) diff --git a/.github/workflows/sphinxbuild.yml b/.github/workflows/sphinxbuild.yml index 50aa183ac70..e194b806b81 100644 --- a/.github/workflows/sphinxbuild.yml +++ b/.github/workflows/sphinxbuild.yml @@ -60,7 +60,6 @@ jobs: uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3 - name: Get stable branches - if: github.ref == 'refs/heads/master' || github.base_ref == 'master' id: stable_branches run: | branches=$(git ls-remote --heads origin "heads/stable[0-9][0-9]" \ @@ -68,30 +67,28 @@ jobs: | sort -n -r | tr '\n' ' ') echo "branches=$branches" >> $GITHUB_OUTPUT - - name: Setup PHP for version validation - if: github.ref == 'refs/heads/master' || github.base_ref == 'master' + - name: Setup PHP for version detection uses: shivammathur/setup-php@7c071dfe9dc99bdf297fa79cb49ea005b9fcadbc # v2.37.1 - - name: Validate version constants in conf.py - if: github.ref == 'refs/heads/master' || github.base_ref == 'master' + - name: Detect and export version constants env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | + # Detect current highest released stable and lowest supported stable via + # GitHub API (same logic as build/build-index.php and generate-top-index.yml). + # Exports DOCS_VERSION_STABLE and DOCS_VERSION_START so conf.py always has + # accurate values without manual updates to any branch. eval $(php build/detect-versions.php ${{ steps.stable_branches.outputs.branches }}) + echo "DOCS_VERSION_STABLE=$highest_stable" >> $GITHUB_ENV + echo "DOCS_VERSION_START=$lowest_stable" >> $GITHUB_ENV - conf_stable=$(grep -m1 '^\s*version_stable\s*=' conf.py | grep -o '[0-9]\+') - conf_start=$(grep -m1 '^\s*version_start\s*=' conf.py | grep -o '[0-9]\+') - - err=0 - if [ "$highest_stable" != "$conf_stable" ]; then - echo "::error::version_stable in conf.py ($conf_stable) != highest released stable ($highest_stable). Update conf.py." - err=1 - fi - if [ "$lowest_stable" != "$conf_start" ]; then - echo "::error::version_start in conf.py ($conf_start) != lowest existing stable branch ($lowest_stable). Update conf.py." - err=1 + # Compute display version: branch number for stableNN builds, dev version for master. + branch="${GITHUB_BASE_REF:-${GITHUB_REF#refs/heads/}}" + if [[ "$branch" =~ ^stable([0-9]+)$ ]]; then + echo "DOCS_DISPLAY_VERSION=${BASH_REMATCH[1]}" >> $GITHUB_ENV + else + echo "DOCS_DISPLAY_VERSION=$((highest_stable + 1))" >> $GITHUB_ENV fi - exit $err - name: Set up Python uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0 diff --git a/_shared_assets/static/custom.css b/_shared_assets/static/custom.css index 59343649db7..e5f57c06c27 100644 --- a/_shared_assets/static/custom.css +++ b/_shared_assets/static/custom.css @@ -229,3 +229,44 @@ table.docutils { #code-style table.docutils { width: 100%; } + +/* Version picker lists — 2-column grid, emoji as absolute ::before bullet */ +.rst-versions .rst-other-versions { + padding-left: 26px; +} + +.rst-versions .rst-other-versions dl.nc-versions-list, +.rst-versions .rst-other-versions dl.nc-languages-list { + display: grid; + grid-template-columns: 1fr 1fr; + gap: 8px; + padding: 6px; +} + +.rst-versions .rst-other-versions dl.nc-versions-list dt, +.rst-versions .rst-other-versions dl.nc-languages-list dt { + grid-column: span 2; + position: relative; + padding: 0; +} + +.rst-versions .rst-other-versions dl dt::before { + position: absolute; + left: -22px; + height: 18px; + width: 18px; + font-size: 16px; + line-height: 18px; +} + +.rst-versions .rst-other-versions dl.nc-versions-list dt::before { + content: "☁️"; +} + +.rst-versions .rst-other-versions dl.nc-languages-list dt::before { + content: "🌐"; +} + +.rst-versions .rst-other-versions dd a { + padding: 0; +} diff --git a/admin_manual/_templates/versions.html b/admin_manual/_templates/versions.html index 5213b763607..9833558216b 100644 --- a/admin_manual/_templates/versions.html +++ b/admin_manual/_templates/versions.html @@ -13,10 +13,10 @@