From d32b0453ff86ae7e4d86881c10dc24549cb0e1b4 Mon Sep 17 00:00:00 2001 From: Ajay Thorve Date: Wed, 15 Jul 2026 15:49:08 -0700 Subject: [PATCH] fix local docs version selector interaction (#353) * fix docs version switcher in local previews Signed-off-by: Ajay Thorve * fix local docs consent overlay Signed-off-by: Ajay Thorve * fix local consent modal loop Signed-off-by: Ajay Thorve --------- Signed-off-by: Ajay Thorve --- docs/README.md | 7 +++++ docs/source/_static/js/local-preview.js | 35 +++++++++++++++++++++++++ docs/source/conf.py | 9 +++++-- docs/source/versions-local.json | 19 ++++++++++++++ 4 files changed, 68 insertions(+), 2 deletions(-) create mode 100644 docs/source/_static/js/local-preview.js create mode 100644 docs/source/versions-local.json diff --git a/docs/README.md b/docs/README.md index 5cc05be79..6f1f30eaf 100644 --- a/docs/README.md +++ b/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. diff --git a/docs/source/_static/js/local-preview.js b/docs/source/_static/js/local-preview.js new file mode 100644 index 000000000..17cbe1277 --- /dev/null +++ b/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); +})(); diff --git a/docs/source/conf.py b/docs/source/conf.py index 554aeeec2..3590018a9 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -6,6 +6,7 @@ _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"] @@ -13,6 +14,10 @@ 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 diff --git a/docs/source/versions-local.json b/docs/source/versions-local.json new file mode 100644 index 000000000..954335c9b --- /dev/null +++ b/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/" + } +]