docs: version-channel awareness (conf.py + switcher JS)

Foundation for multi-version hosting (docs.openmv.io/<channel>/...):
- conf.py: OPENMV_DOCS_CHANNEL env var (default 'dev'); language switcher,
  hreflang, and canonical URLs are now channel-prefixed; html_baseurl is
  per-channel; expose current_version + a bootstrap versions list for
  Shibuya's nav-versions switcher.
- nav-versions.js: populate the version switcher from a site-root
  /versions.json with per-page links that keep the current language, so even
  frozen old snapshots show the full current version list.
- lang-redirect.js: channel-aware -- auto-route language within the current
  version channel instead of at the site root.

No CI/deploy changes yet; live site unaffected (branch only).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: kwagyeman

docs/conf.py

@@ -42,6 +42,13 @@
 _build_date_value = _dt.date.today()
 build_date = _build_date_value.strftime("%d %b %Y")
 
+# Documentation version channel for this build -- the top-level URL segment the
+# site is hosted under (docs.openmv.io/<channel>/...). The CI sets it: "dev" for
+# the rolling master build, "v5.0.0" etc. for a tagged release snapshot. Old
+# release snapshots are frozen HTML and never rebuilt; "/latest/" and "/" are
+# redirect shims to the newest release. Defaults to "dev" for local builds.
+doc_channel = os.environ.get("OPENMV_DOCS_CHANNEL", "dev")
+
 # Values exposed to topindex.html and footer templates.
 # Resolve this submodule's HEAD SHA at build time so "Edit this
 # page" and the AI dropdown's raw-source link both pin to the exact
@@ -75,8 +82,9 @@
 
 # Site root — used by sphinx-llms-txt to emit absolute URLs in
 # /llms.txt and by Shibuya's "Copy page" / "Open in ChatGPT" dropdown
-# to fetch raw page source from /_sources/.
-html_baseurl = "https://docs.openmv.io/"
+# to fetch raw page source from /_sources/. Version-channel aware: every build
+# is hosted under docs.openmv.io/<channel>/.
+html_baseurl = "https://docs.openmv.io/{}/".format(doc_channel)
 
 # -- Landing page code examples (rendered via Pygments to match site code style) --
 from pygments import highlight as _pygments_highlight
@@ -356,38 +364,57 @@ def _render_landing_code(src):
 #   sphinx-build -b html -D language=zh_CN . _build/html/zh_CN
 #   sphinx-build -b html -D language=zh_TW . _build/html/zh_TW
 #
-# The zh_CN / zh_TW entries below go live once those builds are deployed.
-# English first (default), then A–Z by English language name.
+# (display name, language subdirectory, hreflang). English is the bare root of
+# the version channel; each translation lives under <subdir>/. English first,
+# then A–Z by English language name.
+_languages = [
+    ("English",              "",      "en"),
+    ("العربية",              "ar",    "ar"),       # Arabic
+    ("简体中文",              "zh_CN", "zh-Hans"),  # Chinese (Simplified)
+    ("繁體中文",              "zh_TW", "zh-Hant"),  # Chinese (Traditional)
+    ("Hrvatski",             "hr",    "hr"),       # Croatian
+    ("Čeština",              "cs",    "cs"),       # Czech
+    ("Nederlands",           "nl",    "nl"),       # Dutch
+    ("Suomi",                "fi",    "fi"),       # Finnish
+    ("Français",             "fr",    "fr"),       # French
+    ("Deutsch",              "de",    "de"),       # German
+    ("עברית",                "he",    "he"),       # Hebrew
+    ("Magyar",               "hu",    "hu"),       # Hungarian
+    ("Bahasa Indonesia",     "id",    "id"),       # Indonesian
+    ("Italiano",             "it",    "it"),       # Italian
+    ("日本語",                "ja",    "ja"),       # Japanese
+    ("한국어",                "ko",    "ko"),       # Korean
+    ("Polski",               "pl",    "pl"),       # Polish
+    ("Português (Brasil)",   "pt_BR", "pt-BR"),    # Portuguese (Brazil)
+    ("Português (Portugal)", "pt_PT", "pt-PT"),    # Portuguese (Portugal)
+    ("Română",               "ro",    "ro"),       # Romanian
+    ("Русский",              "ru",    "ru"),       # Russian
+    ("Español",              "es",    "es"),       # Spanish
+    ("Svenska",              "sv",    "sv"),       # Swedish
+    ("ไทย",                  "th",    "th"),       # Thai
+    ("Türkçe",               "tr",    "tr"),       # Turkish
+    ("Українська",           "uk",    "uk"),       # Ukrainian
+    ("Tiếng Việt",           "vi",    "vi"),       # Vietnamese
+]
+# Channel-prefixed URL patterns; %s is the page name (filled by Shibuya's
+# i18n_link). Switching language keeps the current version + page, e.g.
+# "/dev/de/%s.html". English is "/dev/%s.html".
 html_context["languages"] = [
-    ("English",    "/%s.html",       "en"),
-    ("العربية",    "/ar/%s.html",    "ar"),       # Arabic
-    ("简体中文",    "/zh_CN/%s.html", "zh-Hans"),  # Chinese (Simplified)
-    ("繁體中文",    "/zh_TW/%s.html", "zh-Hant"),  # Chinese (Traditional)
-    ("Hrvatski",   "/hr/%s.html",    "hr"),       # Croatian
-    ("Čeština",    "/cs/%s.html",    "cs"),       # Czech
-    ("Nederlands", "/nl/%s.html",    "nl"),       # Dutch
-    ("Suomi",      "/fi/%s.html",    "fi"),       # Finnish
-    ("Français",   "/fr/%s.html",    "fr"),       # French
-    ("Deutsch",    "/de/%s.html",    "de"),       # German
-    ("עברית",      "/he/%s.html",    "he"),       # Hebrew
-    ("Magyar",     "/hu/%s.html",    "hu"),       # Hungarian
-    ("Bahasa Indonesia", "/id/%s.html", "id"),    # Indonesian
-    ("Italiano",   "/it/%s.html",    "it"),       # Italian
-    ("日本語",      "/ja/%s.html",    "ja"),       # Japanese
-    ("한국어",      "/ko/%s.html",    "ko"),       # Korean
-    ("Polski",     "/pl/%s.html",    "pl"),       # Polish
-    ("Português (Brasil)",   "/pt_BR/%s.html", "pt-BR"),  # Portuguese (Brazil)
-    ("Português (Portugal)", "/pt_PT/%s.html", "pt-PT"),  # Portuguese (Portugal)
-    ("Română",     "/ro/%s.html",    "ro"),       # Romanian
-    ("Русский",    "/ru/%s.html",    "ru"),       # Russian
-    ("Español",    "/es/%s.html",    "es"),       # Spanish
-    ("Svenska",    "/sv/%s.html",    "sv"),       # Swedish
-    ("ไทย",        "/th/%s.html",    "th"),       # Thai
-    ("Türkçe",     "/tr/%s.html",    "tr"),       # Turkish
-    ("Українська", "/uk/%s.html",    "uk"),       # Ukrainian
-    ("Tiếng Việt", "/vi/%s.html",    "vi"),       # Vietnamese
+    (label,
+     "/{c}/{p}%s.html".format(c=doc_channel, p=(sub + "/" if sub else "")),
+     hreflang)
+    for (label, sub, hreflang) in _languages
 ]
 
+# Documentation-version switcher (Shibuya's nav-versions component, rendered
+# left of the language switcher). ``current_version`` is the button label.
+# ``versions`` is only a bootstrap so the element renders; the real,
+# always-current list -- with per-page links that keep the current language --
+# is populated client-side from /versions.json by static/nav-versions.js, so
+# even frozen old snapshots show the full, current version list.
+html_context["current_version"] = doc_channel
+html_context["versions"] = [(doc_channel, "")]
+
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
 # today = ''
@@ -577,6 +604,10 @@ def _render_landing_code(src):
     # Re-publish --sy-s-offset-top from the real header height so sticky
     # elements stay aligned when the navbar wraps (long translated labels).
     "navbar-height.js",
+    # Populate the version switcher from /versions.json (per-page links that
+    # keep the current language), so even frozen old snapshots list every
+    # version. See static/nav-versions.js.
+    "nav-versions.js",
 ]
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied

docs/static/lang-redirect.js

@@ -1,24 +1,22 @@
 /*
  * Automatic language selection for the OpenMV docs.
  *
- * Each translation is deployed under its own top-level subdirectory
- * (/zh_CN/, /de/, ...) with English at the site root. On first visit this
- * script sends the reader to the build that best matches their browser
- * locale, falling back to English when nothing matches.
+ * The site is versioned: every page lives under a top-level version channel,
+ * docs.openmv.io/<channel>/... ("dev" = rolling master build, "vX.Y.Z" = frozen
+ * release snapshots). Within a channel, English is at the channel root and each
+ * translation lives under <channel>/<lang>/. On first visit this script sends
+ * the reader to the build matching their browser locale -- keeping the current
+ * version channel -- falling back to English when nothing matches.
  *
  * A reader's explicit choice from the navbar "Translations" switcher is
- * remembered (localStorage) and always wins over browser detection, so the
- * switcher is never fought by the auto-redirect. Runs synchronously from
- * <head> so the swap happens before paint, and uses location.replace so it
- * never pollutes history (no back-button trap / redirect loop).
+ * remembered (localStorage) and always wins over browser detection. Runs
+ * synchronously from <head> so the swap happens before paint, and uses
+ * location.replace so it never pollutes history (no back-button trap / loop).
  */
 (function () {
   "use strict";
 
   // Language subdirectories that actually exist (mirror conf.py languages).
-  // he/ar are translated and selectable in the switcher; their layout ships
-  // left-to-right for now (the theme has no RTL chrome) but the text reads
-  // correctly, so they are auto-routed like every other locale.
   var SUBDIRS = ["zh_CN", "zh_TW", "de", "ja", "es", "ru", "fr", "ko", "it", "pt_BR", "nl",
                  "ro", "hr", "cs", "pl", "fi", "sv", "hu", "tr", "ar", "he",
                  "vi", "id", "th", "uk", "pt_PT"];
@@ -39,13 +37,30 @@
 
   var STORE_KEY = "omvLangPref"; // "en" or a subdir; set on manual switch.
 
+  // Path layout: ["", <channel>, <lang?>, ...page]. The language, if any, is the
+  // segment right after the channel.
   function langOfPath(pathname) {
-    var parts = pathname.split("/");
-    // parts[0] is "" (leading slash); first real segment is parts[1].
-    if (parts.length > 1 && SUBDIRS.indexOf(parts[1]) !== -1) return parts[1];
+    var p = pathname.split("/");
+    if (p.length > 2 && SUBDIRS.indexOf(p[2]) !== -1) return p[2];
     return "en";
   }
 
+  function channelOf(pathname) {
+    var p = pathname.split("/");
+    return p.length > 1 ? p[1] : "";
+  }
+
+  // Rebuild the path for `target` language, keeping the version channel + page.
+  function pathForLang(pathname, target) {
+    var p = pathname.split("/");
+    var channel = p[1] || "";
+    var inner = p.slice(2);                                  // [<lang?>, ...page]
+    var curLang = (inner.length && SUBDIRS.indexOf(inner[0]) !== -1) ? inner[0] : "en";
+    var page = (curLang === "en") ? inner : inner.slice(1);  // page segments only
+    var langSeg = (target === "en") ? [] : [target];
+    return "/" + [channel].concat(langSeg, page).join("/");
+  }
+
   function detectFromBrowser() {
     var langs = (navigator.languages && navigator.languages.length)
       ? navigator.languages
@@ -62,17 +77,6 @@
     return "en"; // fallback
   }
 
-  function stripLang(pathname, cur) {
-    if (cur === "en") return pathname;
-    var rest = pathname.replace(new RegExp("^/" + cur + "(?=/|$)"), "");
-    return rest === "" ? "/" : rest;
-  }
-
-  function withLang(pathname, target) {
-    if (target === "en") return pathname;
-    return "/" + target + pathname;
-  }
-
   function safeGet() {
     try { return localStorage.getItem(STORE_KEY); } catch (e) { return null; }
   }
@@ -84,7 +88,8 @@
 
   // Remember the reader's explicit choice when they use the switcher, so it
   // overrides browser detection on later visits. The Shibuya switcher renders
-  // plain <a> links; capture clicks on anything pointing at a known build.
+  // plain <a> links; capture clicks on anything pointing at another language
+  // build of the current page.
   document.addEventListener("click", function (ev) {
     var a = ev.target && ev.target.closest ? ev.target.closest("a[href]") : null;
     if (!a) return;
@@ -93,19 +98,20 @@
     try { path = new URL(href, window.location.href).pathname; }
     catch (e) { return; }
     var chosen = langOfPath(path);
-    // Only treat it as a language choice if it targets the current page in
-    // another build (the switcher links do exactly this).
     if (chosen !== current) safeSet(chosen);
   }, true);
 
-  var pref = safeGet();
-  var target = pref ? pref : detectFromBrowser();
-  if (SUBDIRS.indexOf(target) === -1 && target !== "en") target = "en";
+  // Only auto-route when we are actually under a version channel.
+  if (channelOf(window.location.pathname)) {
+    var pref = safeGet();
+    var target = pref ? pref : detectFromBrowser();
+    if (SUBDIRS.indexOf(target) === -1 && target !== "en") target = "en";
 
-  if (target !== current) {
-    var newPath = withLang(stripLang(window.location.pathname, current), target);
-    if (newPath !== window.location.pathname) {
-      window.location.replace(newPath + window.location.search + window.location.hash);
+    if (target !== current) {
+      var newPath = pathForLang(window.location.pathname, target);
+      if (newPath !== window.location.pathname) {
+        window.location.replace(newPath + window.location.search + window.location.hash);
+      }
     }
   }
 })();

docs/static/nav-versions.js

@@ -0,0 +1,74 @@
+/*
+ * Populate the documentation version switcher (Shibuya's .nav-versions) from a
+ * site-root /versions.json, with per-page links that keep the current language.
+ *
+ * Why client-side: every version is hosted under its own top-level path
+ * (docs.openmv.io/<channel>/...) -- "dev" is the rolling master build, each
+ * "vX.Y.Z" is a frozen HTML snapshot that is never rebuilt. A frozen snapshot's
+ * server-rendered switcher could only list versions that existed when it was
+ * built; fetching the always-current /versions.json at load time means even old
+ * snapshots show the full, current list.
+ *
+ * versions.json format (kept stable so old frozen snapshots can read new files):
+ *   { "versions": [ {"id": "dev", "label": "dev"},
+ *                   {"id": "v5.0.0", "label": "v5.0.0 (latest)"} ],
+ *     "latest": "v5.0.0" }
+ *
+ * Switching version keeps the rest of the path (language subdir + page), so you
+ * stay on the same page in the same language. If that page does not exist in the
+ * target version, that version's 404 shim handles the redirect.
+ */
+(function () {
+  "use strict";
+
+  function channelOf(pathname) {
+    var p = pathname.split("/");           // ["", "<channel>", ...rest]
+    return p.length > 1 ? p[1] : "";
+  }
+
+  // Everything after the leading /<channel> segment, e.g. "/de/library/index.html".
+  function tailOf(pathname) {
+    var p = pathname.split("/");
+    return "/" + p.slice(2).join("/");
+  }
+
+  function populate(data) {
+    var box = document.querySelector(".nav-versions");
+    if (!box || !data || !Array.isArray(data.versions)) return;
+    var choices = box.querySelector(".nav-versions-choices");
+    if (!choices) return;
+
+    var cur = channelOf(window.location.pathname);
+    var tail = tailOf(window.location.pathname);
+
+    var ul = document.createElement("ul");
+    data.versions.forEach(function (v) {
+      var id = typeof v === "string" ? v : v.id;
+      var label = (typeof v === "object" && v.label) ? v.label : id;
+      var li = document.createElement("li");
+      var a = document.createElement("a");
+      a.href = "/" + id + tail;
+      a.textContent = label;
+      if (id === cur) a.setAttribute("aria-current", "true");
+      li.appendChild(a);
+      ul.appendChild(li);
+    });
+
+    var existing = choices.querySelector("ul");
+    if (existing) existing.replaceWith(ul);
+    else choices.appendChild(ul);
+  }
+
+  function load() {
+    fetch("/versions.json", { cache: "no-cache" })
+      .then(function (r) { return r.ok ? r.json() : null; })
+      .then(function (data) { if (data) populate(data); })
+      .catch(function () { /* offline / local build: keep the server bootstrap */ });
+  }
+
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", load);
+  } else {
+    load();
+  }
+})();