feat(docs): serve werf 3 documentation as the latest version

.helm/values.yaml

@@ -45,7 +45,7 @@ resources:
       production: 300M
 
 docs:
-  currentRoot: v2
+  currentRoot: v3
   supportedRoots:
     - v3
     - v2

.werf/nginx-dev.conf

@@ -87,8 +87,8 @@ http {
 
         location /docs/ {
             rewrite ^/docs/?$ /docs/latest/ redirect;
-            rewrite ^/docs/(?<ver>latest|pr-[^/]+|v2(?:\.[^/]+)?|v1\.2(?:\.[^/]+)?)$ /docs/$ver/ redirect;
-            rewrite ^/docs/(?<ver>latest|pr-[^/]+|v2(?:\.[^/]+)?|v1\.2(?:\.[^/]+)?)/(?<tail>.*) /$tail break;
+            rewrite ^/docs/(?<ver>latest|pr-[^/]+|v3(?:\.[^/]+)?|v2(?:\.[^/]+)?|v1\.2(?:\.[^/]+)?)$ /docs/$ver/ redirect;
+            rewrite ^/docs/(?<ver>latest|pr-[^/]+|v3(?:\.[^/]+)?|v2(?:\.[^/]+)?|v1\.2(?:\.[^/]+)?)/(?<tail>.*) /$tail break;
 
             proxy_set_header  Host              $http_host;
             proxy_set_header  X-Real-IP         $remote_addr;

Taskfile.yaml

@@ -153,6 +153,12 @@ tasks:
       - |
         ./scripts/docs/check_broken_links.sh en
 
+  site:check-docs-roots:
+    desc: "Check that docs roots, the latest alias and doc group detection agree with the current docs root."
+    cmds:
+      - |
+        ./scripts/docs/check_docs_roots.sh
+
   site:run-spell-check:
     desc: "Run spell check for all pages."
     deps:

_data/en/topnav.yml

@@ -1,7 +1,7 @@
 - title: Getting Started
   url: /getting_started/
 - title: Documentation
-  url: /docs/v2/
+  url: /docs/v3/
 - title: Kubernetes guide
   url: /guides.html
   hot: true

_data/ru/topnav.yml

@@ -1,7 +1,7 @@
 - title: Быстрый старт
   url: /getting_started/
 - title: Документация
-  url: /docs/v2/
+  url: /docs/v3/
 - title: Самоучитель по Kubernetes
   url: /guides.html
   hot: true

assets/js/customscripts.js

@@ -467,18 +467,15 @@ $(document).ready(function () {
 });
 
 function getDocGroupFromURL() {
-  let result = window.location.pathname.match(/^\/docs\/(latest|pr-[^/]+|v2(?:\.[^/]+)?|v1\.2(?:\.[^/]+)?)(?:\/|$)/);
+  let result = window.location.pathname.match(/^\/docs\/(latest|pr-[^/]+|v3(?:\.[^/]+)?|v2(?:\.[^/]+)?|v1\.2(?:\.[^/]+)?)(?:\/|$)/);
   if (result && result[1]) {
-    if (result[1] === 'latest') {
-      return 'v2';
-    }
-    if (result[1].indexOf('pr-') === 0) {
-      return 'v2';
-    }
     if (result[1].indexOf('v1.2') === 0) {
       return 'v1.2';
     }
-    return 'v2';
+    if (result[1].indexOf('v2') === 0) {
+      return 'v2';
+    }
+    return 'v3';
   }
   return null;
 }

docker-compose.yml

@@ -47,7 +47,7 @@ services:
   backend:
     image: $WERF_BACKEND_DOCKER_IMAGE_NAME
     environment:
-      CURRENT_DOCS_MAJOR: "v2"
+      CURRENT_DOCS_MAJOR: "v3"
       SUPPORTED_DOCS_MAJOR_VERSIONS: "v3,v2,v1.2"
       DOCS_LATEST_ALIAS_ENABLED: "true"
       LOG_LEVEL: info

robots.txt

@@ -8,6 +8,9 @@ User-agent: *
 Disallow: *.js
 Disallow: *?*
 Allow: /
+Allow: /docs/v3
+Disallow: /docs/v3-
+Disallow: /docs/v3.
 Allow: /docs/v2
 Disallow: /docs/v2-
 Disallow: /docs/v2.

scripts/docs/check_doc_group.js

@@ -0,0 +1,35 @@
+const assert = require("assert");
+const fs = require("fs");
+const path = require("path");
+
+const src = fs.readFileSync(
+  path.join(__dirname, "../../assets/js/customscripts.js"),
+  "utf8",
+);
+const fnSource = src.match(/function getDocGroupFromURL\(\) \{[\s\S]*?\n\}/);
+assert.ok(fnSource, "getDocGroupFromURL is not found in customscripts.js");
+
+const call = (pathname) =>
+  new Function("window", `${fnSource[0]}; return getDocGroupFromURL();`)({
+    location: { pathname },
+  });
+
+const cases = [
+  ["/docs/latest/usage/build/overview.html", "v3"],
+  ["/docs/pr-123/index.html", "v3"],
+  ["/docs/v3/", "v3"],
+  ["/docs/v3.1.4/reference/werf_yaml.html", "v3"],
+  ["/docs/v2/", "v2"],
+  ["/docs/v2.10.3/reference/werf_yaml.html", "v2"],
+  ["/docs/v1.2/", "v1.2"],
+  ["/docs/v1.2.4-plus-fix1/reference/werf_yaml.html", "v1.2"],
+  ["/docs/v9/", null],
+  ["/guides.html", null],
+];
+
+for (const [pathname, want] of cases) {
+  const got = call(pathname);
+  assert.strictEqual(got, want, `${pathname}: got ${got}, want ${want}`);
+}
+
+console.log(`OK: getDocGroupFromURL, ${cases.length} cases`);

scripts/docs/check_docs_roots.sh

@@ -0,0 +1,60 @@
+#!/bin/bash
+
+set -e
+
+cd "$(dirname "$0")/../.."
+
+current_root="v3"
+
+chart_dir="$(mktemp -d)"
+trap 'rm -rf "$chart_dir"' EXIT
+cp -R .helm/. "$chart_dir/"
+cat >"$chart_dir/Chart.yaml" <<EOF
+apiVersion: v2
+name: werfio
+version: 0.0.0
+EOF
+
+fail() {
+  echo "FAIL: $1" >&2
+  exit 1
+}
+
+for cluster in eu ru; do
+  rendered="$(helm template werfio-production "$chart_dir" \
+    --set werf.env=production \
+    --set werf.namespace=werfio-production \
+    --set "werf.image.web-backend=stub" \
+    --set "global.targetCluster=$cluster")"
+
+  echo "$rendered" | grep -q -- "- name: CURRENT_DOCS_MAJOR" ||
+    fail "$cluster: CURRENT_DOCS_MAJOR env is missing"
+  echo "$rendered" | grep -A1 -- "- name: CURRENT_DOCS_MAJOR" | grep -q "value: \"$current_root\"" ||
+    fail "$cluster: CURRENT_DOCS_MAJOR is not $current_root"
+  echo "$rendered" | grep -A1 -- "- name: SUPPORTED_DOCS_MAJOR_VERSIONS" | grep -q 'value: "v3,v2,v1.2"' ||
+    fail "$cluster: supported documentation versions changed"
+  echo "$rendered" | grep -q "rewrite \^/docs/?\$ */docs/$current_root/ " ||
+    fail "$cluster: /docs/ does not redirect to /docs/$current_root/"
+  echo "$rendered" | grep -q "rewrite \^/docs/(?<ver>latest|.*)/?\$ */docs/\$ver/usage/project_configuration/overview.html" ||
+    fail "$cluster: latest alias is missing in docs shortcuts"
+done
+
+grep -q "latest|pr-\[^/\]+|$(echo "$current_root" | sed 's/\./\\\\./')" .werf/nginx-dev.conf ||
+  fail "nginx-dev.conf does not proxy /docs/$current_root/"
+
+for lang in en ru; do
+  grep -q "url: /docs/$current_root/" "_data/$lang/topnav.yml" ||
+    fail "$lang topnav does not link to /docs/$current_root/"
+done
+
+grep -q "CURRENT_DOCS_MAJOR: \"$current_root\"" docker-compose.yml ||
+  fail "local backend does not use $current_root"
+
+for root in v3 v2; do
+  grep -qx "Allow: /docs/$root" robots.txt || fail "robots.txt blocks $root"
+  grep -q "/docs/$root/sitemap.xml" sitemap.xml || fail "sitemap.xml omits $root"
+done
+
+node scripts/docs/check_doc_group.js
+
+echo "OK: docs roots are consistent with currentRoot $current_root"

scripts/docs/spelling/dictionaries/dev_OPS.dic

@@ -1,4 +1,4 @@
-520
+522
 1GB
 2GB
 5XX
@@ -160,6 +160,7 @@ MySQL’s
 namespace
 namespaces
 Nelm
+netavark
 nginx
 NGINX’s
 Node.js
@@ -177,6 +178,7 @@ plugin
 PNG
 PodAntiAffinity
 PodDisruptionBudget
+Podman
 PostgreSQL
 PowerShell
 pre

scripts/docs/spelling/wordlist

@@ -158,6 +158,7 @@ MySQL’s
 namespace
 namespaces
 Nelm
+netavark
 nginx
 NGINX’s
 Node.js
@@ -175,6 +176,7 @@ plugin
 PNG
 PodAntiAffinity
 PodDisruptionBudget
+Podman
 PostgreSQL
 PowerShell
 pre

sitemap.xml

@@ -7,6 +7,9 @@ search: exclude
 <?xml version="1.0" encoding="UTF-8"?>
 
 <sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+   <sitemap>
+      <loc>{{ site.url }}/docs/v3/sitemap.xml</loc>
+   </sitemap>
    <sitemap>
       <loc>{{ site.url }}/docs/v2/sitemap.xml</loc>
    </sitemap>