Forward-merge release/2.2 into develop

docs/README.md

@@ -28,20 +28,22 @@ make -C docs linkcheck
 
 ## Release Metadata
 
-[`source/project.json`](source/project.json) is the single source of truth for the published documentation version.
-The Sphinx configuration reads its `name` and `version` fields, and the NVIDIA Docs publisher uses the same file to
-select the deployment directory.
+[`source/project.json`](source/project.json) defines the published documentation version. The Sphinx configuration
+reads its `name` and `version` fields, and the NVIDIA Docs publisher uses the same file to select the deployment
+directory. [`source/versions1.json`](source/versions1.json) is the publisher index deployed at
+`https://docs.nvidia.com/aiq-blueprint/versions1.json`.
 
 Use the exact release artifact version, without a leading `v`. For example, the `v2.2.0-rc1` Git tag uses
-`2.2.0-rc1`. Update only `source/project.json` when advancing the documentation version.
+`2.2.0-rc1`. When advancing the documentation version, update `source/project.json` and the preferred entry in
+`source/versions1.json` together; the Sphinx build fails when they diverge.
 
-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 version switcher always reads the publisher index from the absolute URL
+`https://docs.nvidia.com/aiq-blueprint/versions1.json`. The generated HTML also includes `versions1.json` at its root
+so the deployment handoff can publish the global index. Do not change the switcher back to a relative URL; relative
+paths 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.
+with the bundled same-origin `source/versions1.json` and suppresses the production consent UI without changing consent
+state, so the overlay does not block local page controls. Deployed documentation continues to use the absolute index
+URL and normal consent behavior.

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

@@ -10,7 +10,7 @@
   const currentScript = document.currentScript;
   if (currentScript && typeof DOCUMENTATION_OPTIONS !== "undefined") {
     DOCUMENTATION_OPTIONS.theme_switcher_json_url = new URL(
-      "../../versions-local.json",
+      "../../versions1.json",
       currentScript.src,
     ).href;
   }

docs/source/conf.py

@@ -6,17 +6,17 @@
 
 _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"))
+_VERSIONS = json.loads((_DOCS_SOURCE_DIR / "versions1.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")
+_PREFERRED_VERSIONS = [entry["version"] for entry in _VERSIONS if entry.get("preferred")]
+if _PREFERRED_VERSIONS != [release]:
+    raise ValueError("versions1.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
@@ -74,7 +74,7 @@
     "show_nav_level": 1,
 }
 
-html_extra_path = ["project.json", "versions-local.json"]
+html_extra_path = ["project.json", "versions1.json"]
 html_static_path = ["_static"]
 html_favicon = "_static/favicon.ico"
 html_css_files = ["css/custom.css"]

docs/source/versions-local.json → docs/source/versions1.json

@@ -2,7 +2,7 @@
     {
         "preferred": true,
         "version": "2.2.0-rc1",
-        "url": "/"
+        "url": "https://docs.nvidia.com/aiq-blueprint/2.2.0-rc1/"
     },
     {
         "version": "2.1.0",