docs(reference): data-driven Reference tab — v1.3.0 refresh + release notes mirror, known issues, deprecations - #8
Merged
Jont828 merged 20 commits intoJul 24, 2026
Conversation
…iven components, add Model Early Access Builds Rebuild the Reference-tab pages on the docs refactor as custom Fern components backed by a single data module (components/releases.data.ts), refreshed from main's reference pages to v1.3.0 GA: - CompatibilityHero, FeatureHeatmap (per-backend coverage scores, numbered caveat footnotes), BackendVersionMatrix (pin-diff highlights across the release history), CudaDriverMatrix (driver ladder showing the CUDA 12 cutoff at v1.3.0), ArtifactBrowser (CSS-only filter rail, click-to-copy tags), ReleaseTimeline, ModelEABuildCards (GA-path badges, per-tag coverage dots), shared ReferenceStyles vocabulary. - New reference/model-early-access-builds.mdx page ported from main; added to the Reference tab nav and redirects. - Fixed pre-existing broken support-matrix/feature-matrix links across backends/, features/, components/, getting-started/ and added /resources/* redirect sources matching the live site URLs. - custom.js: clipboard binder for [data-dynref-copy] buttons. Per-release bumps now touch only releases.data.ts. Design pass ran against a 6-dimension rubric with fresh-context raters (round 1: 3.6/5, round 2 after fixes: 4.61/5, ship gate passed). Signed-off-by: Dan Gil <dagil@nvidia.com>
- Kind pills (GA release / Patch / Early access / Model build) move to a dedicated Type column; stable releases are labeled GA release, not Minor (matrix + timeline). - NIXL cell always renders three stacked per-backend rows. - Per-release history accordions move inline under Backend Dependencies and CUDA & Driver Requirements instead of a buried bottom section. Signed-off-by: Dan Gil <dagil@nvidia.com>
- Add a legend note explaining the pin-change highlight in the version history table (unmarked pins are unchanged vs the previous release). - Delete unused learnMoreLabel/learnMoreHref fields from releases.data.ts (nothing renders them; per-feature source links live in the MDX tabs). Gate evidence: all nine component files pass tsc --strict; fern docs broken-links reports zero errors in the three reference pages (189 pre-existing errors elsewhere on the branch); custom.js passes node --check; key version pins audited against main's reference pages. Signed-off-by: Dan Gil <dagil@nvidia.com>
- Register multimodal-vllm/sglang/trtllm pages in a hidden nav section so Compatibility's per-backend links can resolve. - Darken light-mode accentPrimary to #538300 (2.41:1 -> 4.55:1 contrast). - Consolidate the green/amber tint families into --dynref-* CSS tokens (single source in ReferenceStyles; 54 literals replaced, 5 redundant .dark blocks removed). - Cleanup: remove link-resolution test block. Signed-off-by: Dan Gil <dagil@nvidia.com>
…ges, artifacts streamline Phase A of the reference-docs expansion: - Release Notes: docs-native mirror of the GitHub release notes for v1.0.0+ (verbatim one-time ingestion; patches folded into base pages; contributors in accordions). Per-release ReleaseHeader (GA pill, stat tiles), ReleaseSummaryCards highlight grid, UpgradePanel migration strip. - Known Issues + Deprecations pages split from the release bodies (area badges; Removed/Deprecated/Behavioral kind badges; Migrate guidance preserved); Known Artifact Issues table relocated. - Release Artifacts streamline: timeline promoted + linked to release pages, release links in the browser header, EA explainer accordion. - Compatibility hero: prominent backend names + per-backend CUDA chips. - Agent readability: scripts/gen_llms_tables.py emits llms-only twins into the three componentized pages (idempotent markers). - releases.data.ts notesHref; nav gains Release Notes section, Known Issues, Deprecations with pinned slugs. Verification: fern dev renders all pages; broken-links 0 errors in the nine reference pages (baseline 189 pre-existing); tsc --strict clean; assembly verbatim audit zero drift. Signed-off-by: Dan Gil <dagil@nvidia.com>
Round-2 rater findings (gate was 4.54 with two dimensions below 4): - ReleaseTimeline gains a notes variant: feature-voice summaries for GA releases (new notesSummary field) and no crates table on the Release Notes overview — ends the duplicated artifact-voice history. - UpgradePanel drops the non-interactive from-version chips for plain muted text (single fromVersion API); no false affordance. - Highlight-card area badges flattened to the uniform blue treatment. - Hash deep-links now open the target accordion (hydration-aware handler in custom.js) and re-scroll to the anchor. - Early-access pointer added to every release page's cross-link note. - Terminology unified on 'GA release' (hero + version matrix). - Ledger accordion titles unified to 'vX.Y.Z — N entries' shape. Skipped by design: trimming highlight-card copy (bodies are verbatim mirrors of the GitHub release text). tsc --strict clean; node --check clean; live-verified: overview voice split, blue chips, accordion deep-links, GA release badges. Signed-off-by: Dan Gil <dagil@nvidia.com>
- releases.data.ts header now carries the real per-release bump checklist (data entry, new release page + ingestion-time counts, ledger sections, nav slug, twins regeneration) and points at the generator's parser contract — the old 'bump this file' claim understated the workflow and invited drift. - Blue tint family consolidated into shared --dynref-blue-* tokens (badge--blue, chip--arch, summary-card area chips, upgrade-panel reading chips); redundant .dark blocks pruned — completes the green/amber token pattern from the earlier gate. Gate evidence: tsc --strict clean across all 12 components; gen_llms_tables.py --check passes (parser tolerates the new header, twins fresh); blue tokens verified flipping in both modes live. Signed-off-by: Dan Gil <dagil@nvidia.com>
- Per-release stats single-sourced in RELEASE_STATS (releases.data.ts): ReleaseHeader reads stats by version, UpgradePanel derives reading-list labels/hrefs from (version, kind) pairs, and the Known Issues and Deprecations accordion titles compute their counts via MDX expression attributes — count duplication across pages is gone. Live-verified byte-identical rendered counts. - Remaining color families tokenized (--dynref-teal/orange/violet-*) across chips and artifact-browser glyphs; redundant .dark blocks pruned. Every dynref tint now has exactly one definition. - New scripts/check_reference.sh: one-command gate (twins fresh + parser contract, custom.js parse, stale-link sweep, reference-scoped fern broken-links). Immediately caught 4 pre-existing broken links in reference/observability/operator-metrics.mdx (guide file deleted in an earlier refactor) — repointed to the surviving Kubernetes observability guide; site broken-links baseline drops 189 to 185. - Prod .md-export verification attempted via fern generate --preview: blocked (publisher org membership) — lands with the PR publish pipeline; risk is one-sided (twins verified absent from human render). check_reference.sh ALL CHECKS PASSED; tsc --strict clean across all 12 components; gen_llms_tables.py --check passes with RELEASE_STATS added. Signed-off-by: Dan Gil <dagil@nvidia.com>
|
👋 Hi dagil-nvidia! Thank you for contributing to Jont828/dynamo. Just a reminder: The 🚀 |
github-actions
Bot
added
external-contribution
docs
documentation
…cast asset The docs-website version snapshots (fern/versions/v1.x.yml) reference the digest posts as ../digest/<post>.md, but this branch renamed all six to .mdx — the sync's rm-rf+cp of digest/ then left those .md targets dangling (12 fern check errors). And welcome.mdx points at ./assets/hero-demo-25.cast, which the sync never lands in the root fern/assets/ (1 error). - Sync docs/fern/assets/ into the docs-website root fern/assets/ (merge-copy, mirroring the blogs precedent so older versioned refs survive). - Retarget ../digest/*.md -> .mdx in the preserved version snapshots during sync (leaves ../blogs/*.md alone); a no-op once main commits the rewritten snapshots to docs-website. Reproduced the full sync+check pipeline against a docs-website clone: Found 13 errors -> Found 0 errors (2 pre-existing warnings remain). Signed-off-by: Dan Gil <dagil@nvidia.com>
Upgrade tooling (all CSS-only, data-derived from releases.data.ts): - UpgradeSelector on Deprecations: pick your 1.x line, get the pill-to- pill dependency migration strip and the exact breaking-changes / known-issues reading list spanning every release to current. Reuses UpgradePanel internals via an export refactor (release-page panel renders identically). - RunsWhereWizard on Compatibility: backend x CUDA-driver generation -> qualifying releases with per-row driver floors; pull commands only for the current release; honest empty states (TRT-LLM x CUDA 12). - PinnedEnvironment on Release Artifacts + the v1.3.0 notes page: backend-switched full setup script with a matching copy-all payload; TensorRT-LLM variant omits the wheel per policy. - TagLookup on Release Artifacts: 13 published tags (stable + EA) -> release/build detail cards with GA-path badges and ledger chips. Agent surface: - reference/releases-data.mdx: machine-readable mirror of the full data module, generated by gen_llms_tables.py between idempotent markers; hidden nav entry pins /reference/releases-data. - assets/releases.json + assets/releases-atom.xml emitted by the same generator (deterministic dates, no now()); not site-servable by Fern (assets are CDN-rewritten only when referenced) - fetchable from the repo raw URL post-merge; noted on the Release Notes overview. - Per-section llms.txt verified Fern-native (reference/llms.txt serves on the Fern origin; docs.nvidia.com proxy drops the suffix - flagged as an external follow-up). No docs.yml changes (the available keys would override the auto-generated indexes). Gate: check_reference.sh ALL CHECKS PASSED; tsc --strict clean across all 15 components; generator idempotent incl. new outputs; feed xmllint-valid, JSON valid; all four surfaces live-verified. Signed-off-by: Dan Gil <dagil@nvidia.com>
… de-duplicate the timeline - Group the release pages under a 'Releases' nav section in Reference (Release History + the four release notes pages + Known Issues + Deprecations); landing page retitled Release History. - One canonical timeline: the feature-voice timeline on the Releases landing is now the only release history. Removed the duplicate artifact-voice timeline from Release Artifacts (it pointed at the same releases in a second voice). - Extract the crates.io first-publication table into a standalone CratesFirstPublished component so it renders once, on Release Artifacts (its natural home as crate-publishing metadata), in an accordion. - Release Artifacts now points to the Releases page for full history. Signed-off-by: Dan Gil <dagil@nvidia.com>
- RunsWhereWizard: fix the Current-badge overflow that overlapped the CUDA chip on the v1.3.0 row; add a data-derived empty-state hint. - Keyboard accessibility across every radio-pill rail (wizard, upgrade selector, artifact browser, tag lookup, pinned environment): inputs are visually-hidden (dynref-vh) not display:none, with focus-visible rings on the active pill. - PinnedEnvironment: break the helm line with a shell continuation so it no longer clips; copy-all payload stays byte-identical to the visible script. - TagLookup: align the breaking/known-issue chips to the blue reading-chip treatment used on Deprecations. tsc --strict clean; check_reference.sh ALL CHECKS PASSED. Signed-off-by: Dan Gil <dagil@nvidia.com>
From a fresh-context structural review of the Phase B/C surface:
- Generator: extract 7 shared section renderers (cuda/feature/artifact/
known-issues/crates/platform/ea tables) so the machine-readable page and
the llms-only twins compose them instead of duplicating byte-for-byte
(-43 lines); add the three required-subscript exports to REQUIRED_EXPORTS
so a missing one fails with the clean error; guard build_json against
all-undated input like build_atom. Output proven byte-identical via
golden diff; --check idempotent.
- ReleaseTimeline: drop the now-vestigial variant prop (only the notes
voice is used since the crates table was extracted to CratesFirstPublished);
fix the stale header comment; ReleaseTimeline() takes no args.
- UpgradePanel: drop the dead export on buildReadingChips (internal only).
- Deprecations: keep the v1.3.0 entry-count literal with a source-of-truth
comment — a bare MDX {expression} at paragraph start breaks the page
compile (verified: it 404'd), unlike the sibling accordion title={} attrs.
Reviewer's count-drift finding on the release-notes prose was declined: those
counts are verbatim GitHub mirror (design invariant), and the derived values
render from RELEASE_STATS via ReleaseHeader; both verified consistent today.
tsc --strict clean; check_reference.sh ALL CHECKS PASSED; fern check 0 errors.
Signed-off-by: Dan Gil <dagil@nvidia.com>
…i-dynamo) The refactor branch had drifted to organization ai-dynamo and instance ai-dynamo.docs.buildwithfern.com/dynamo, which no account can publish to. dynamo main is authoritative: organization nvidia, instance dynamo.docs.buildwithfern.com/dynamo with the docs.nvidia.com/dynamo custom domains. Aligned both so previews and publishes route to the real org. Verified: fern generate --docs --preview now publishes (267 pages). Signed-off-by: Dan Gil <dagil@nvidia.com>
The Reference tab's General variant (Compatibility, Release Artifacts, Releases, Known Issues, Deprecations, Model EA Builds, Glossary) is cumulative metadata about releases, so version snapshots should render it always-current instead of freezing a stale copy. This uses Fern's native shared-content model: every version's nav references the same pages-dev source files. - release-version job: the pages-vX.Y.Z snapshot drops exactly the files the General variant references (derived from dev.yml, so versioned reference/ content like observability and runtime-config stays frozen), and the generated versions/vX.Y.Z.yml keeps that variant's paths on ../pages-dev/. The Kubernetes API and Components variants stay on the frozen snapshot. - sync job: after each main push, the General variant's nav block from dev.yml is propagated into every post-rework versions/v*.yml, so pages added to the shared reference (e.g. a new release-notes page) appear in every version dropdown. Pre-rework snapshots have no such variant and are skipped untouched. Validated by simulating both jobs locally against the current docs-website tip (cutting a v1.4.0): the generated version yml carries the intended shared/frozen path split, pre-rework version files are byte-untouched, and fern check reports an identical error set to a control run with the unmodified logic (all pre-existing, none in reference/). Signed-off-by: Dan Gil <dagil@nvidia.com>
… + gate the class Moving Known Issues, Deprecations, and the release-notes pages under the Releases nav section changed their URLs to /reference/releases/..., but the absolute hrefs hardcoded in components and the data module kept the old shape and 404 on the live preview (verified: /dynamo/dev/reference/ deprecations 404s, /dynamo/dev/reference/releases/deprecations 200s). - Fix the six component href sites (ReleaseHeader, UpgradePanel, TagLookup breaking/known-issues chips), the ten notesHref values in releases.data.ts, and the Atom feed index URL in gen_llms_tables.py (now the release-history landing page); regenerate releases-data.mdx, releases.json, and releases-atom.xml from the fixed data. - check_reference.sh gains step 4/5: every absolute /dynamo/dev/reference/... href in components, the data module, generated assets, and reference pages must match a URL derived from the index.yml Reference General variant (explicit slug or kebab-cased title, section slugs included). fern broken-links cannot see hrefs in TSX/JSON, which is exactly how this class escaped. Negative-tested: a reintroduced stale href fails the gate with file:line. Full gate passes: twins fresh, custom.js parses, no stale matrix links, 12 published reference URLs all matched, 0 broken links in reference/. Signed-off-by: Dan Gil <dagil@nvidia.com>
If the reference tab or its General variant is renamed, the shared- reference exclusion and nav revert in the release job silently no-op and new version snapshots quietly freeze their own reference copy — the site keeps working, so nothing surfaces the regression. Emit a workflow warning annotation so the rename gets caught on the first tag cut. Signed-off-by: Dan Gil <dagil@nvidia.com>
…ploy-manifest embeds
Two pre-existing missing-file classes would fail the first post-merge
publish to docs-website (96 fern check errors on the composed tree; the
preview never hits them because it builds from the source layout):
- Component doc pages (64 errors): the nav references .md/.mdx pages
under components/ from the Developer Guide tab and the Reference tab's
Components variant, but the sync rsync excludes components/ wholesale
(so React .tsx sync separately to fern/components/ for mdx-components
resolution). Add a second targeted rsync that copies only .md/.mdx
under components/ into pages-dev/components/ — the .tsx all sit at the
components/ root and the 38 doc pages all sit in subdirectories, so
nothing duplicates, and the release job's snapshot keeps freezing the
config references per version as intended.
- Backend deploy manifests (32 errors): templates/{vllm,sglang,trtllm}
.mdx embed repo files via <Code src="../../../examples/backends/
<engine>/deploy/*.yaml">, which resolve against the repo root in the
source layout but have no counterpart on docs-website. Sync just the
referenced backends/*/deploy/ subtrees to the branch root; the same
relative depth resolves from pages-dev and from version snapshots.
Validated by simulating the sync and release jobs against the current
docs-website tip with a v1.4.0 cut: fern check on the composed tree goes
from 96 errors to 0, no .tsx lands in pages-dev, all 38 doc pages and 86
deploy manifests sync, and the frozen snapshot carries the doc pages.
The sync job's git add -A picks up both new trees unchanged.
Signed-off-by: Dan Gil <dagil@nvidia.com>
The fern-docs.yml sync and release-version jobs only execute on main pushes and tag cuts, so composition changes (rsync scopes, nav path transforms, the shared-Reference machinery) were validated by an ephemeral scratchpad script that the next contributor could not rerun. Land it as docs/fern/scripts/simulate_docs_website.sh: replays both jobs against a temporary worktree of the local docs-website branch and asserts the invariants — fern check reports 0 errors on the composed tree, the generated version yml keeps the Reference General variant shared while Kubernetes API and Components stay frozen, the snapshot drops exactly the shared files, no .tsx leaks into pages-dev, pre-rework version files gain no shared-reference pointers, and a page added to the shared reference after a version is cut propagates into that version's nav (round two). Portable: derives paths from the repo root, no hardcoded scratch dirs, perl instead of sed -i, python 3.10+ detection, fern check degrades to a warning when the CLI is absent. shellcheck clean; full run passes all 7 assertions against the current docs-website tip. The workflow header now points at the harness so it gets rerun before the next composition change. Signed-off-by: Dan Gil <dagil@nvidia.com>
UCX ships with each release's NIXL builds, so surface it wherever the NIXL pins already render. Values are transcribed from the releases' own Key Dependencies tables: 1.20 (v1.1.0), 1.20.0 (v1.2.0), 1.20.x (v1.3.0). v1.0.0 and the patch releases never stated one, so they render a dash rather than an inferred value. - releases.data.ts: optional ucx field on Release (+ bump checklist) - BackendVersionMatrix: UCX column after NIXL, with the same changed-since-previous-release highlight; the previous-release helper now returns the Release so non-pin fields can diff too - UpgradePanel/UpgradeSelector: UCX row in the migration strip directly under the NIXL rows, skipped when either side has no stated value - gen_llms_tables.py: UCX column in both generated pin tables; releases.json picks the field up via the existing passthrough Twins regenerated and idempotent; check_reference.sh full pass. Signed-off-by: Dan Gil <dagil@nvidia.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Rebuilds the Reference tab as a data-driven component suite, refreshed to v1.3.0 GA, and adds a docs-native release notes mirror with upgrade tooling and an agent-readable surface. 12 commits, 42 files, +11.7k lines. Validates clean (
fern check: 267 pages, 0 errors); every value derives from one data module, verified against the current reference pages with nothing invented.Pages
Compatibility (
reference/compatibility.mdx)Release Artifacts (
reference/release-artifacts.mdx)Releases (new nav section)
reference/known-issues.mdx): split verbatim from the release bodies, backend-badged rows, artifact issues absorbedreference/deprecations.mdx): kind-badged ledger (Removed / Deprecated / Behavioral) with Migrate callouts and an upgrade selector (pick your version -> the reading list to current)Model Early Access Builds (
reference/model-early-access-builds.mdx)Releases (machine-readable) (
reference/releases-data.mdx, hidden)docs/fern/assets/releases.json,releases-atom.xml)Under the hood
components/releases.data.tsdrives every page — a release bump is largely a one-file edit (checklist in the module header; per-release counts single-sourced inRELEASE_STATS).components/(no client JS); shared--dynref-*design tokens; CSS-only interactivity throughout, dark and light.<llms-only>markdown twins of the component data on each componentized page, generated byscripts/gen_llms_tables.py(idempotent, fail-closed parser).scripts/check_reference.sh: one-command gate (twins fresh, custom.js parse, stale-link sweep, reference-scoped broken-links).Also fixes (pre-existing, not ours)
.github/workflows/fern-docs.yml): the version snapshots referenced digest posts as.mdwhile this branch renamed them.mdx, and a welcome-page cast asset was never synced to the fern root — both brokefern checkin the preview build. Fixed in-sync.reference/observability/operator-metrics.mdx(guide file deleted in an earlier refactor); site broken-links baseline drops 189 -> 185.Review notes
fern docs broken-links: zero errors inreference/.docs/recipes/inkling.mdx); repoint on next main sync.compatibility(redirects already indocs.yml); these pages supersede main's four reference pages on merge..mdexports of the componentized pages to confirm the<llms-only>twins serve to agents (they're confirmed invisible in the human render; the export behavior is the one thing dev preview can't exercise).🤖 Generated with Claude Code