fix local docs version selector interaction

[AjayThorve]

Overview

Fix the documentation version selector when generated HTML is served from localhost or another loopback address.

There are two independent browser failures:

1. https://docs.nvidia.com/aiq-blueprint/versions1.json does not return an Access-Control-Allow-Origin header, so browsers block local previews from reading the publisher-managed index and the NVIDIA Sphinx theme leaves the selector empty.
2. The production OneTrust consent overlay loads on localhost and intercepts pointer events, preventing the populated selector from being clicked.

This change preserves the publisher-managed version index and normal consent behavior for deployed documentation. On loopback hosts only, a local-preview bootstrap uses a bundled same-origin version index and suppresses the production consent UI with CSS. It does not accept cookies, reject cookies, or mutate consent state. The Sphinx configuration also rejects builds when the local index's preferred version diverges from project.json.

DCO sign-off for the squash commit

Signed-off-by: Ajay Thorve athorve@nvidia.com
Signed-off-by: Ajay Thorve AjayThorve@users.noreply.github.com

Validation

• I ran the relevant local checks or explained why they are not applicable.
  • pre-commit run --files docs/source/conf.py docs/source/versions-local.json docs/source/_static/js/local-preview.js docs/README.md
  • uv run --extra docs sphinx-build -M html docs/source docs/build
  • uv run --extra docs sphinx-build -M linkcheck docs/source docs/build
  • Served docs/build/html with python3 -m http.server 3000 and exercised /get-started/ using Playwright with a fresh system Chrome profile.
  • After 15 seconds, verified one main-frame navigation, zero requests for /, no visible consent banner or overlay, a clickable 2.2.0-rc1 selector, and menu entries for 2.2.0-rc1, 2.1.0, 2.0.0, and 1.2.1.
• I added or updated tests for behavior changes.
  • The static bootstrap behavior was exercised through the generated HTML in a real browser; this repository has no checked-in browser-test harness for the Sphinx theme.
• I updated documentation for user-facing or contributor-facing changes.
• I confirmed this PR does not include secrets, credentials, or internal-only data.
• I certify this contribution under the Developer Certificate of Origin (DCO) and signed my commits with git commit -s or an equivalent sign-off.
• I replaced the DCO sign-off placeholder with my GitHub commit identity and kept the required angle brackets around the email address.

Where should reviewers start?

Review docs/source/_static/js/local-preview.js for the loopback-only behavior and docs/source/conf.py for the build-time version invariant.

Related Issues

• Relates to fix docs release version and coverage #345

Summary by CodeRabbit

• New Features

  • Added local documentation preview support with a version switcher for available documentation releases.
  • Local previews now use a bundled versions list and automatically identify the preferred release.
  • Consent banners are hidden during local previews while consent settings remain preserved.

• Documentation

  • Added guidance explaining local preview behavior and distinguishing it from deployed documentation.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: dc57a29b-d7d6-4c55-a9ed-d27299ad99b2

📥 Commits

Reviewing files that changed from the base of the PR and between c859946 and 5fdd096.

📒 Files selected for processing (4)

• docs/README.md
• docs/source/_static/js/local-preview.js
• docs/source/conf.py
• docs/source/versions-local.json

---

Walkthrough

Adds validated local documentation version metadata and a hostname-gated preview script that rewrites the version switcher URL and hides production consent UI during local previews.

Changes

Local documentation preview

Layer / File(s)	Summary
Local version metadata and build wiring docs/source/conf.py, docs/source/versions-local.json	Sphinx validates that the current release is the sole preferred local version, publishes versions-local.json, and includes local-preview.js in generated HTML.
Local preview runtime behavior docs/source/_static/js/local-preview.js, docs/README.md	Supported local hostnames use the local version index, hide OneTrust elements, preserve consent state, and document the distinction from deployed documentation behavior.

Estimated code review effort: 2 (Simple) | ~10 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Browser
  participant local-preview.js
  participant DOCUMENTATION_OPTIONS
  participant versions-local.json
  Browser->>local-preview.js: Load on a supported local hostname
  local-preview.js->>DOCUMENTATION_OPTIONS: Rewrite theme_switcher_json_url
  Browser->>versions-local.json: Fetch local version metadata
  local-preview.js->>Browser: Inject styles hiding OneTrust UI

Loading

Possibly related PRs

• NVIDIA-AI-Blueprints/aiq#345: Both changes update Sphinx version-switcher metadata and html_extra_path handling.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}