Skip to content

Keep documentation version links as a fallback - #195

Merged
tpn merged 3 commits into
mainfrom
codex/docs-versions-fallback-20261114
Nov 16, 2026
Merged

tpn merged 3 commits into
mainfrom
codex/docs-versions-fallback-20261114

Conversation

@tpn

@tpn tpn commented Nov 14, 2026

Copy link
Copy Markdown
Collaborator

Summary

Hide the extra Versions link when the documentation dropdown is usable, while keeping it available when JavaScript or catalog loading is unavailable. Give the fallback page the guide's fonts, light/dark colors, responsive spacing, and visible keyboard focus.

Validation

  • Existing developer suite: 190 passed; strict developer typing, Ruff/format, and commit hooks pass.
  • Browser checks on copied real guide output: 10 scenarios covering normal loading, failed/invalid catalogs, JavaScript disabled, desktop/mobile layouts, light/dark palettes, and keyboard navigation. Screenshots inspected.

Repository hygiene

  • No credentials, private paths, local datasets, notebook outputs, or generated run artifacts were added.
  • Large binary artifacts are excluded or intentionally tracked through an approved storage plan.
  • Security-sensitive information is not included.
  • User-visible behavior changes are documented.
  • New dependencies and their licenses are documented.

Hide the extra Versions link when the dropdown is usable. Keep the
link available when scripts or catalog loading are unavailable, and
style its destination with the guide's palette and typography.

Signed-off-by: Trent Nelson <trentn@nvidia.com>
@tpn
tpn requested a review from melo-gonzo as a code owner November 14, 2026 21:49
@coderabbitai

coderabbitai Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

The versions page now includes inline responsive styles for layout, typography, links, keyboard focus, and dark mode. The selector stylesheet hides an adjacent anchor when the version select is enabled.

Changes: Archive presentation

Layer / File(s) Summary
Versions page styles
dev/src/cuphoton_dev/archive.py
The versions page adds layout, typography, link, keyboard-focus, and dark-mode styles.
Selector adjacent-link visibility
dev/src/cuphoton_dev/assets/selector.css
The stylesheet hides an adjacent anchor when #cuphoton-version-select is enabled.

Possibly related PRs

  • NVIDIA/cuPhoton#187: Adds a shared version selector and versioned guide catalog. This pull request also changes version-selector and catalog behavior.
Merge Risk: Minimal · up to 8d408

This is a presentation-only change: it styles the fallback Versions page and hides the redundant link when the dropdown works. It has little production risk and can be reverted easily.

Architecture risk: Low · up to 96af5

The change affects 1 system.

Changed systems: dev

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

  • observed — dev (service) was modified; 2 changed files map to changed impact.

Before / after behavior

  • observed — Modified behavior in dev/src/cuphoton_dev/archive.py: The versions page now includes inline CSS for page layout and typography, styled version links and hover states, a visible keyboard-focus outline, and dark-mode colors. Previously, the title was followed directly by the page body without these styles.
  • observed — Modified behavior in dev/src/cuphoton_dev/assets/selector.css: Adds a rule that hides an adjacent anchor when #cuphoton-version-select is enabled.
Pre-merge checks: Passed 2

Check name Status Explanation
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Recent review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between 4557e07 and 8d40887.

Files selected for processing: 1

  • dev/src/cuphoton_dev/archive.py
Files skipped from review as they are similar to previous changes: 1

  • dev/src/cuphoton_dev/archive.py

Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 11 remain after this review.

@tpn tpn added the ai-review Request a focused CodeRabbit review label Nov 15, 2026

@melo-gonzo melo-gonzo left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks. I read this at 96af56b, and the fallback logic holds. This is from code reading; I did not render the guide.

  • Each page renders the <select> disabled, with the Versions link right after it (transforms.py:276-285), so the new rule matches.
  • selector.js enables the select only after it loads a valid catalog that lists the current version. A failed fetch, a wrong schema or a missing version all leave it disabled, so the link still shows. The same holds with JavaScript off.
  • check_archive only checks that versions.html exists, so the new page style does not trip validation of the retained archive.

Three notes for a follow-up. None blocks this PR.

  • In light mode, the link text on the hover background is 4.26:1. That is under the 4.5:1 WCAG AA level for normal text. A link color of #387a00 gives 5.31:1 on white and 4.93:1 on hover. Dark mode passes.
  • Each snapshot has a copy of selector.css under _version/ (transforms.py:322-325). _reuse keeps release snapshots whatever the controller commit (publisher.py:180-190). Released guides therefore keep the Versions link next to the dropdown, and only main and later releases get this change. assemble rebuilds versions.html for the whole archive, so the new page style shows everywhere.
  • The rule depends on the link coming right after the <select>. A check in test_transforms.py that soup.select_one("#cuphoton-version-select + a") finds the versions.html link would catch a markup change that leaves the link always visible.
Contrast ratios (WCAG 2 relative luminance)
light link   #3f8500 on #ffffff  4.60
light hover  #3f8500 on #f5f7f2  4.26
dark link    #76b900 on #181818  7.36
dark hover   #76b900 on #252821  6.20
proposed     #387a00 on #ffffff  5.31, on #f5f7f2  4.93

tpn added 2 commits November 16, 2026 10:52
Darken light-theme version links so their normal and hover colors meet
the contrast minimum for normal-sized text.

Signed-off-by: Trent Nelson <trentn@nvidia.com>
@tpn
tpn merged commit d8d8c76 into main Nov 16, 2026
60 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ai-review Request a focused CodeRabbit review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants