Merge pull request #15140 from nextcloud/fix/numbered-version-in-titles

fix: show numbered version in manual titles and version picker

Author: skjnldsv

.github/workflows/sphinxbuild.yml

@@ -59,6 +59,40 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
+      - 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]" \
+            | awk '{gsub(/^refs\/heads\/stable/, "", $2); print $2}' \
+            | 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'
+        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'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          eval $(php build/detect-versions.php ${{ steps.stable_branches.outputs.branches }})
+
+          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
+          fi
+          exit $err
+
       - name: Set up Python
         uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
@@ -242,7 +276,10 @@ jobs:
           if [[ "$branch" == stable* ]]; then
             echo "release=${branch#stable}" >> $GITHUB_OUTPUT
           else
-            echo "release=latest" >> $GITHUB_OUTPUT
+            # For master (latest), derive the dev version from conf.py so the
+            # PDF cover shows a real version number rather than "latest".
+            version_stable=$(grep -m1 '^\s*version_stable\s*=' conf.py | grep -o '[0-9]\+')
+            echo "release=$((version_stable + 1))" >> $GITHUB_OUTPUT
           fi
 
       - name: Build pdf documentation

admin_manual/_templates/versions.html

@@ -9,20 +9,20 @@
             data-toggle="rst-current-version"
             aria-expanded="false"
             aria-controls="rst-other-versions-admin">
-      ☁️ {{ current_version }}
+      ☁️ {{ display_version }}
       <span class="fa fa-caret-down" aria-hidden="true"></span>
     </button>
     <div id="rst-other-versions-admin" class="rst-other-versions">
       <dl>
         <dt>☁️ {{ _('Versions') }}</dt>
-        {% for slug, url in versions|reverse %}
+        {% for slug, url, label in versions|reverse %}
         <dd style="width: 32%">
           <a href="{{ url }}"
              {% if current_version == slug %}
              style="color: var(--dark-link-color);"
              {% endif %}
           >
-            {{ slug }}
+            {{ label }}
           </a>
         </dd>
         {% endfor %}

admin_manual/conf.py

@@ -20,7 +20,8 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = u'Nextcloud %s Administration Manual' % (version)
+project = u'Nextcloud %s Administration Manual' % (display_version)
+html_title = project
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

build/build-index.php

@@ -1,82 +1,6 @@
 <?php
 require_once 'server-block.php';
-
-/**
- * Get the GitHub API headers with optional authentication
- */
-function get_github_headers(): string {
-	$headers = 'User-Agent: Nextcloud Documentation Builder';
-	if ($token = getenv('GITHUB_TOKEN')) {
-		$headers .= "\r\nAuthorization: token $token";
-	}
-	return $headers;
-}
-
-/**
- * Get the repository name for a given version
- * Nextcloud moved to nextcloud-releases/server starting with version 32
- */
-function get_repo_for_version(int $version): string {
-	return $version >= 32 ? 'nextcloud-releases/server' : 'nextcloud/server';
-}
-
-/**
- * Parse the HTTP status code from the response headers populated by file_get_contents.
- *
- * @param array $headers The $http_response_header array
- */
-function parse_http_status(array $headers): int {
-	preg_match('/HTTP\/[\d.]+ (\d+)/', $headers[0] ?? '', $matches);
-	return (int)($matches[1] ?? 0);
-}
-
-/**
- * Fetch release info for a given version from the GitHub API.
- *
- * Returns an array ['date' => int] if the release exists (HTTP 200).
- * Returns null if the release does not exist (HTTP 404).
- * Exits with code 1 on any other HTTP status (rate limit, server error, etc.)
- * to prevent silently generating empty or incorrect index sections.
- */
-function fetch_release_info(int $version): ?array {
-	$repo = get_repo_for_version($version);
-	$url = sprintf('https://api.github.com/repos/%s/releases/tags/v%d.0.0', $repo, $version);
-
-	$context = stream_context_create([
-		'http' => [
-			'header' => get_github_headers(),
-			'timeout' => 10,
-			'ignore_errors' => true
-		]
-	]);
-
-	$response = @file_get_contents($url, false, $context);
-
-	// FIXME: function_exists conditional can be dropped once we don't need to support <8.4.0
-	if (function_exists('http_get_last_response_headers')) {
-		/** @var array|null */
-		$http_response_header = \http_get_last_response_headers();
-	}
-
-	$status = isset($http_response_header) && is_array($http_response_header)
-		? parse_http_status($http_response_header)
-		: 0;
-
-	if ($status === 200) {
-		$data = json_decode($response, true);
-		$publishedAt = $data['published_at'] ?? $data['created_at'] ?? null;
-		return ['date' => $publishedAt ? strtotime($publishedAt) : time()];
-	}
-
-	if ($status === 404) {
-		return null;
-	}
-
-	// Any non-200/non-404 response (403 rate limit, 429, 5xx, network failure)
-	// must abort so we never deploy an index with empty or wrong sections.
-	fwrite(STDERR, "GitHub API error (HTTP $status) checking v$version.0.0 — aborting to avoid deploying incorrect index\n");
-	exit(1);
-}
+require_once 'detect-versions.php';
 
 // Parse and validate command-line arguments
 /** @var int[] */
@@ -90,47 +14,16 @@ function fetch_release_info(int $version): ?array {
 	exit(1);
 }
 
-// Fetch release information from GitHub
-$released_branches = [];
-$oneYearAgo = time() - (365 * 24 * 60 * 60);
-$foundOutOfSupport = null;
-
-foreach ($branches as $branch) {
-	if ($foundOutOfSupport !== null) {
-		fwrite(STDOUT, "🛑 Version $branch is unsupported (older than version $foundOutOfSupport)\n");
-		$released_branches[$branch] = $releaseTime;
-		$releaseType = $releaseTime >= $oneYearAgo ? 'stable' : 'unsupported';
-		continue;
-	}
-
-	$info = fetch_release_info($branch);
-	if ($info === null) {
-		fwrite(STDERR, "⏳ Version $branch is not released (tag v$branch.0.0 not found)\n");
-		continue;
-	}
-
-	$releaseTime = $info['date'];
-	$released_branches[$branch] = $releaseTime;
-	if ($releaseTime < $oneYearAgo) {
-		fwrite(STDOUT, "🛑 Version $branch is unsupported (released on " . date('Y-m-d', $releaseTime) . ")\n");
-		$foundOutOfSupport = $branch;
-	} else {
-		fwrite(STDOUT, "✅ Version $branch is supported (released on " . date('Y-m-d', $releaseTime) . ")\n");
-	}
-}
-
-// Determine development version
-if (isset($released_branches[$branches[0]])) {
-	$devVersion = $branches[0] + 1;
-	$devStatus = 'development';
-} else {
-	$devVersion = $branches[0];
-	$devStatus = 'upcoming';
-}
+// Detect version metadata (API calls happen here)
+$versions = detect_versions($branches);
+$released_branches = $versions['released'];
+$devVersion = $versions['dev_version'];
+$devStatus = isset($released_branches[$branches[0]]) ? 'development' : 'upcoming';
 
 fwrite(STDERR, "➡️ Version $devVersion ($devStatus)\n");
 
 // Collect released stable versions within support window
+$oneYearAgo = time() - (365 * 24 * 60 * 60);
 $stableVersions = [];
 foreach ($branches as $branch) {
 	if (isset($released_branches[$branch]) && $released_branches[$branch] >= $oneYearAgo) {