Forward-merge release/2.2 into develop

docs/README.md

@@ -38,3 +38,10 @@ Use the exact release artifact version, without a leading `v`. For example, the
 The version switcher reads the publisher-managed index at
 `https://docs.nvidia.com/aiq-blueprint/versions1.json`. Do not add a per-build `versions1.json`; a copied index becomes
 stale and relative switcher URLs resolve differently on top-level and nested pages.
+
+The publisher-managed index does not allow cross-origin browser requests, so a preview served from a loopback host
+cannot read it directly. For local previews, `source/_static/js/local-preview.js` replaces the switcher URL at runtime
+with the bundled `source/versions-local.json` and suppresses the production consent UI without changing consent state,
+so the overlay does not block local page controls. Keep the local index's preferred entry aligned with
+`source/project.json`; the Sphinx build fails when they diverge. Deployed documentation continues to use the
+publisher-managed index and consent behavior.

docs/source/_static/js/local-preview.js

@@ -0,0 +1,35 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+(() => {
+  const localHosts = new Set(["localhost", "127.0.0.1", "0.0.0.0", "::1"]);
+  if (!localHosts.has(window.location.hostname)) {
+    return;
+  }
+
+  const currentScript = document.currentScript;
+  if (currentScript && typeof DOCUMENTATION_OPTIONS !== "undefined") {
+    DOCUMENTATION_OPTIONS.theme_switcher_json_url = new URL(
+      "../../versions-local.json",
+      currentScript.src,
+    ).href;
+  }
+
+  const localPreviewStyles = document.createElement("style");
+  localPreviewStyles.dataset.aiqLocalPreview = "true";
+  localPreviewStyles.textContent = `
+    #onetrust-consent-sdk,
+    #onetrust-banner-sdk,
+    #onetrust-pc-sdk,
+    .onetrust-pc-dark-filter {
+      display: none !important;
+      pointer-events: none !important;
+    }
+
+    html,
+    body {
+      overflow: auto !important;
+    }
+  `;
+  document.head.append(localPreviewStyles);
+})();

docs/source/conf.py

@@ -6,13 +6,18 @@
 
 _DOCS_SOURCE_DIR = Path(__file__).resolve().parent
 _PROJECT_METADATA = json.loads((_DOCS_SOURCE_DIR / "project.json").read_text(encoding="utf-8"))
+_LOCAL_VERSIONS = json.loads((_DOCS_SOURCE_DIR / "versions-local.json").read_text(encoding="utf-8"))
 _PUBLISHED_DOCS_URL = "https://docs.nvidia.com/aiq-blueprint"
 
 project = _PROJECT_METADATA["name"]
 copyright = "2025-%Y, NVIDIA Corporation"
 author = "NVIDIA Corporation"
 release = _PROJECT_METADATA["version"]
 
+_LOCAL_PREFERRED_VERSIONS = [entry["version"] for entry in _LOCAL_VERSIONS if entry.get("preferred")]
+if _LOCAL_PREFERRED_VERSIONS != [release]:
+    raise ValueError("versions-local.json must mark the project.json version as the single preferred version")
+
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
@@ -69,11 +74,11 @@
     "show_nav_level": 1,
 }
 
-html_extra_path = ["project.json"]
+html_extra_path = ["project.json", "versions-local.json"]
 html_static_path = ["_static"]
 html_favicon = "_static/favicon.ico"
 html_css_files = ["css/custom.css"]
-html_js_files = ["js/mermaid-fullscreen.js"]
+html_js_files = ["js/local-preview.js", "js/mermaid-fullscreen.js"]
 html_show_sourcelink = False
 
 # Suppress warnings for missing toctree references during incremental builds

docs/source/versions-local.json

@@ -0,0 +1,19 @@
+[
+    {
+        "preferred": true,
+        "version": "2.2.0-rc1",
+        "url": "/"
+    },
+    {
+        "version": "2.1.0",
+        "url": "https://docs.nvidia.com/aiq-blueprint/2.1.0/"
+    },
+    {
+        "version": "2.0.0",
+        "url": "https://docs.nvidia.com/aiq-blueprint/2.0.0/"
+    },
+    {
+        "version": "1.2.1",
+        "url": "https://docs.nvidia.com/aiq-blueprint/1.2.1/"
+    }
+]