fix: index generation and add tests

skjnldsv · skjnldsv · commit 8baaf9fb4186 · 2026-04-01T17:35:17.000+02:00
Signed-off-by: skjnldsv &lt;skjnldsv@protonmail.com&gt;
diff --git a/.github/workflows/generate-top-index.yml b/.github/workflows/generate-top-index.yml
@@ -4,14 +4,20 @@ on:
   push:
     branches:
       - master
+  pull_request:
+    branches:
+      - master
+
+permissions:
+  contents: write
 
 jobs:
   build:
     name: Build index.html
     runs-on: ubuntu-latest
 
     permissions:
-      contents: write
+      contents: read
 
     steps:
     - name: Cache git metadata
@@ -31,7 +37,7 @@ jobs:
     - name: Get stable branches
       id: branch
       run: |
-        branches=$(git ls-remote --heads origin "stable[0-9]*" | awk '{gsub(/^refs\/heads\/stable/, "", $2); print $2}' | sort -n -r | tr '\n' ' ')
+        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
@@ -43,14 +49,22 @@ jobs:
         mv build/index.html /tmp/index.html
         mv build/static/ /tmp/static/
 
+    - name: Verify index.html structure and links
+      run: |
+        # Temporarily put index.html in build folder for verification
+        cp /tmp/index.html build/index.html
+        php build/verify-index.php
+
     - name: Switch to gh-pages branch
+      if: github.event_name == 'push'
       run: |
         git fetch origin gh-pages
         git checkout gh-pages
         git config --local user.email "action@github.com"
         git config --local user.name "GitHub Action"
     
     - name: Commit and push changes
+      if: github.event_name == 'push'
       run: |
         # Move the generated index.html and static files to the root of the gh-pages branch
         rm -rf index.html static/
diff --git a/.github/workflows/sphinxbuild.yml b/.github/workflows/sphinxbuild.yml
@@ -12,6 +12,7 @@ permissions:
 
 jobs:
   build:
+
     name: Build ${{ matrix.manual.name }}
     runs-on: ubuntu-latest
 
@@ -119,7 +120,7 @@ jobs:
         current_branch="${GITHUB_REF#refs/heads/}"
 
         # Find the highest numbered stable branch from the remote
-        highest_stable=$(git ls-remote --heads origin 'stable[0-9]*' | sed 's?.*refs/heads/stable??' | sort -n | tail -1)
+        highest_stable=$(git ls-remote --heads origin "heads/stable[0-9][0-9]"' | sed 's?.*refs/heads/stable??' | sort -n | tail -1)
         highest_stable_branch="stable${highest_stable}"
 
         echo "Current branch: $current_branch"
diff --git a/.github/workflows/update-workflow.yml b/.github/workflows/update-workflow.yml
@@ -51,9 +51,22 @@ jobs:
         echo "Checking out file: ${{ inputs.file_path }} from master branch"
         git checkout origin/master -- ${{ inputs.file_path }}
     
+    - name: Adjust Python version for older branches
+      run: |
+        # Extract version from branch name (e.g., stable32 -> 32)
+        VERSION=$(echo "${{ matrix.target_branch }}" | sed 's/stable//')
+        
+        # For branches stable19-stable31, use Python 3.10 instead of 3.12
+        if [ "$VERSION" -le 31 ]; then
+          if grep -q "python-version: 3.12" "${{ inputs.file_path }}"; then
+            sed -i 's/python-version: 3\.12/python-version: 3.10/g' "${{ inputs.file_path }}"
+            echo "Updated Python version to 3.10 for stable$VERSION"
+          fi
+        fi
+    
     - name: Commit and push changes
       run: |
         git add ${{ inputs.file_path }}
-        git commit -sm "chore: update ${{ inputs.file_path }} from master branch"
+        git diff --cached --quiet || git commit -sm "chore: update ${{ inputs.file_path }} from master branch"
         
         git push origin ${{ matrix.target_branch }}
diff --git a/build/build-index.php b/build/build-index.php
@@ -1,49 +1,156 @@
 <?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';
+}
+
+/**
+ * Check if a version is officially released by querying the GitHub tag
+ */
+function is_version_released(int $version): bool {
+	$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' => 5,
+			'ignore_errors' => true
+		]
+	]);
+	
+	$response = @file_get_contents($url, false, $context);
+	
+	if (isset($http_response_header) && is_array($http_response_header)) {
+		return strpos($http_response_header[0] ?? '', '200') !== false;
+	}
+	
+	return $response !== false;
+}
+
+/**
+ * Fetch release date for a version from GitHub API
+ */
+function get_release_date(int $version): ?int {
+	$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' => 5
+		]
+	]);
+	
+	$response = @file_get_contents($url, false, $context);
+	if ($response === false) {
+		return null;
+	}
+	
+	$data = json_decode($response, true);
+	$publishedAt = $data['published_at'] ?? $data['created_at'] ?? null;
+	return $publishedAt ? strtotime($publishedAt) : null;
+}
+
+// Parse and validate command-line arguments
 /** @var int[] */
 $branches = array_slice($argv, 1);
 $branches = array_filter($branches, fn($b) => is_numeric($b));
 rsort($branches, SORT_NUMERIC);
-
-// We added this script when we had only 12 and above.
 $branches = array_filter($branches, fn($b) => $b >= 12);
 
 if (empty($branches)) {
 	fwrite(STDERR, "Error: No valid stable branches were provided. Please pass at least one numeric branch >= 12.\n");
 	exit(1);
 }
 
-// Generate current development version section
-$sections = [generate_section(($branches[0] + 1), 0)];
+// Fetch release information from GitHub
+$released_branches = [];
+$oneYearAgo = time() - (365 * 24 * 60 * 60);
+$foundOutOfSupport = false;
 
-// Generate stable version section
-foreach ($branches as $index => $v) {
-	$sections[] = generate_section($v, $index + 1);
+foreach ($branches as $branch) {
+	if ($foundOutOfSupport) {
+		fwrite(STDERR, "⊘ Version $branch not checked (older than first out-of-support version)\n");
+		continue;
+	}
+	
+	if (!is_version_released($branch)) {
+		fwrite(STDERR, "✗ Version $branch not released (tag v$branch.0.0 not found)\n");
+		continue;
+	}
+	
+	$releaseTime = get_release_date($branch);
+	if ($releaseTime === null) {
+		$releaseTime = time();
+	}
+	
+	$released_branches[$branch] = $releaseTime;
+	$releaseType = $releaseTime >= $oneYearAgo ? 'stable' : 'unsupported';
+	fwrite(STDERR, "✓ Version $branch released on " . date('Y-m-d', $releaseTime) . " ($releaseType)\n");
+	
+	if ($releaseType === 'unsupported') {
+		$foundOutOfSupport = true;
+	}
 }
 
-// Insert into index.html
-$index = file_get_contents(__DIR__ . '/index-template.html');
+// Determine development version
+if (isset($released_branches[$branches[0]])) {
+	$devVersion = $branches[0] + 1;
+	$devStatus = 'development';
+} else {
+	$devVersion = $branches[0];
+	$devStatus = 'upcoming';
+}
 
-$supported = array_slice($sections, 0, 4);
-$legacy = array_slice($sections, 4);
+fwrite(STDERR, "⬗ Version $devVersion ($devStatus)\n");
 
-$index = str_replace(
-	'<!-- SERVER SUPPORTED BLOCK -->',
-	implode("\n", $supported),
-	$index
-);
+// Collect released stable versions within support window
+$stableVersions = [];
+foreach ($branches as $branch) {
+	if (isset($released_branches[$branch]) && $released_branches[$branch] >= $oneYearAgo) {
+		$stableVersions[] = $branch;
+	} elseif (isset($released_branches[$branch])) {
+		// Once we hit an unsupported version, stop
+		break;
+	}
+}
 
-$index = str_replace(
-	'<!-- SERVER LEGACY BLOCK -->',
-	implode("\n", $legacy),
-	$index
-);
+// Generate sections with proper indices
+$supported = [generate_section($devVersion, 0)];
+foreach ($stableVersions as $idx => $version) {
+	// Index 3 for the oldest supported version if there are multiple
+	$index = ($idx + 1 === count($stableVersions) && count($stableVersions) > 1) ? 3 : $idx + 1;
+	$supported[] = generate_section($version, $index);
+}
 
-$index = str_replace(
-	'<!-- CURRENT_YEAR -->',
-	date('Y'),
-	$index
-);
+// Generate legacy sections (released but outside support window)
+$legacy = [];
+foreach ($branches as $branch) {
+	if (isset($released_branches[$branch]) && !in_array($branch, $stableVersions)) {
+		$legacy[] = generate_section($branch, 1);
+	}
+}
 
+// Generate and write final index.html
+$index = file_get_contents(__DIR__ . '/index-template.html');
+$index = str_replace('<!-- SERVER SUPPORTED BLOCK -->', implode("\n", $supported), $index);
+$index = str_replace('<!-- SERVER LEGACY BLOCK -->', implode("\n", $legacy), $index);
+$index = str_replace('<!-- CURRENT_YEAR -->', date('Y'), $index);
 file_put_contents(__DIR__ . '/index.html', $index);
diff --git a/build/verify-index.php b/build/verify-index.php
@@ -0,0 +1,110 @@
+<?php
+/**
+ * Verify index.html structure and links validity
+ * 
+ * Checks:
+ * - Template placeholders are replaced
+ * - Version sections exist
+ * - Links are properly formatted
+ * - External links are accessible
+ */
+
+$html_file = 'build/index.html';
+
+if (!file_exists($html_file)) {
+	fwrite(STDERR, "⚠️  $html_file not found\n");
+	exit(0);
+}
+
+$content = file_get_contents($html_file);
+
+// Verify template placeholders are replaced
+if (strpos($content, 'SERVER SUPPORTED BLOCK') !== false || strpos($content, 'SERVER LEGACY BLOCK') !== false) {
+	fwrite(STDERR, "❌ ERROR: Template placeholders not replaced in index.html!\n");
+	exit(1);
+}
+
+// Extract all href attributes
+$links = [];
+if (preg_match_all('/href=(["\'])([^\'"]+)\1/', $content, $matches)) {
+	$links = array_unique($matches[2]);
+}
+
+fprintf(STDERR, "✓ Found %d unique links in index.html\n", count($links));
+
+// Categorize links
+$fragment_links = array_filter($links, fn($l) => strpos($l, '#') === 0);
+$external_links = array_filter($links, fn($l) => preg_match('~^https?://~', $l));
+$relative_links = array_filter($links, fn($l) => strpos($l, '#') !== 0 && !preg_match('~^https?://~', $l));
+
+fprintf(STDERR, "  - Fragment links: %d\n", count($fragment_links));
+fprintf(STDERR, "  - External links: %d\n", count($external_links));
+fprintf(STDERR, "  - Relative links: %d\n", count($relative_links));
+
+// Verify structure is present
+if (!preg_match('/<h2>Nextcloud \d+/', $content)) {
+	fwrite(STDERR, "❌ ERROR: No version sections found in index.html!\n");
+	exit(1);
+}
+
+$version_count = preg_match_all('/<h2>Nextcloud (\d+)/', $content, $versions);
+fprintf(STDERR, "✓ Found %d version sections: %s\n", $version_count, implode(', ', $versions[1]));
+
+// Validate documentation links format (should be /server/VERSION/)
+$docs_links = array_filter($external_links, fn($l) => preg_match('~docs\.[^/]+/server/~', $l));
+
+if (!empty($docs_links)) {
+	$invalid_docs = array_filter($docs_links, fn($l) => 
+		!preg_match('~/server/(latest|stable|\d+)/~', $l)
+	);
+	
+	if (!empty($invalid_docs)) {
+		fprintf(STDERR, "⚠️  WARNING: %d potentially malformed documentation links detected:\n", count($invalid_docs));
+		foreach (array_slice($invalid_docs, 0, 3) as $link) {
+			fprintf(STDERR, "    - %s\n", $link);
+		}
+	} else {
+		fprintf(STDERR, "✓ All %d documentation links are properly formatted\n", count($docs_links));
+	}
+}
+
+// Check accessibility of external links (sample first 5)
+fprintf(STDERR, "\nVerifying external links...\n");
+$unreachable = [];
+$external_sample = array_slice($external_links, 0, 5);
+
+foreach ($external_sample as $link) {
+	$context = stream_context_create([
+		'http' => [
+			'method' => 'HEAD',
+			'timeout' => 5,
+			'ignore_errors' => true,
+			'user_agent' => 'Mozilla/5.0'
+		]
+	]);
+	
+	$response = @get_headers($link, true, $context);
+	
+	if ($response === false) {
+		fprintf(STDERR, "  ⚠️  %s - connection failed (may be temporary)\n", $link);
+	} else {
+		$status_line = $response[0] ?? '';
+		if (preg_match('/\d{3}/', $status_line, $match)) {
+			$status = (int)$match[0];
+			if ($status >= 400) {
+				$unreachable[] = [$link, $status];
+				fprintf(STDERR, "  ⚠️  %s returned %d\n", $link, $status);
+			} else {
+				fprintf(STDERR, "  ✓ %s\n", $link);
+			}
+		}
+	}
+}
+
+if (count($unreachable) >= 3) {
+	fprintf(STDERR, "\n❌ ERROR: %d links are unreachable!\n", count($unreachable));
+	exit(1);
+}
+
+fprintf(STDERR, "\n✓ index.html validation passed\n");
+exit(0);
