Repository navigation
fix(docs): repair dead links and redirect dead paths across published versions - #16792
Conversation
… reference pages Release snapshots drop their reference/general copies in favor of the shared pages-dev files, but links inside the snapshot still named the dropped copies and rendered as raw paths that 404. A new relink step after the drop points those links at the pages-dev copies, with a unit test and a matching simulate_docs_website.sh assertion. Also fixes broken links on main: reference-style link definitions on the compatibility page, links to pages outside the nav, the zh-CN quickstart cards and image paths, the NGC container URL, and the Inkling recipe link. Signed-off-by: Dan Gil <dagil@nvidia.com>
Adds exact redirects for 984 paths that published pages link to but that 404 or render as missing pages, across dev, latest, every released version, and zh-CN. Internal destinations are live pages; repository files point at GitHub at the matching tag. The entries sit above the pattern rules, which would otherwise send 23 of them to pages that are also gone. Signed-off-by: Dan Gil <dagil@nvidia.com>
Signed-off-by: Dan Gil <dagil@nvidia.com>
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
There was a problem hiding this comment.
Previously reported defects still present:
- Original discussion: The English and Chinese v1.1.1 backend redirects still target
/dynamo/v1.1.1/backends, but that navigation entry is only a section and has no landing page. - Original discussion: The changed Chinese quickstart Card hrefs still resolve under the stale
fern/pagestree, while their targets are published fromfern/pages-dev; the translation resolver does not rewrite JSX hrefs. - Original discussion: The release workflow still invokes the new relinker from
source-checkout, which is checked out at the requested tag. Force-rebuilding any older published tag therefore fails because that checkout does not contain the script.
WalkthroughThis change adds shared-reference relinking to the versioned documentation workflow, makes the pre-merge broken-links check strict, and updates documentation links and image paths, including in Chinese translations. ChangesDocumentation Link Handling
Priority: ➖ Normal Estimated code review effort: 3 (Moderate) | ~20 minutes Merge Risk: 🟡 Moderate · up to
|
| Check name | Status | Explanation |
|---|---|---|
| Title check | The title clearly summarizes the primary changes: repairing dead documentation links and redirecting dead paths across published versions. | |
| Linked Issues check | Check skipped because no linked issues were found for this pull request. | |
| Out of Scope Changes check | Check skipped because no linked issues were found for this pull request. | |
| Description check | The description clearly explains the changes and includes validation results. It identifies the related Linear issue as DYN-5011. It does not include the requested "Where should the reviewer start?" s… |
Full details: Description check
-
Explanation
The description clearly explains the changes and includes validation results. It identifies the related Linear issue as DYN-5011. It does not include the requested "Where should the reviewer start?" section, and the issue reference uses "Refs" instead of the template's explicit "Closes" or "Relates to" format.
Full details: Docstring Coverage
-
Explanation
Docstring coverage is 12.50% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 8 functions across 4 files. (13 skipped: 13 unsupported.)
Resolution
Write docstrings for the functions missing them to satisfy the coverage threshold.
- Fix all pre-merge checks with AI
- Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Comment @coderabbitai help to get the list of available commands.
…workflow ref Signed-off-by: Dan Gil <dagil@nvidia.com>
Signed-off-by: Dan Gil <dagil@nvidia.com>
dmitry-tokarev-nv
left a comment
There was a problem hiding this comment.
Reviewed head 54f5dc7d4f3c92089c85ebc53f6fa26894c56394. No P0 or P1 found. This review has one P2 and two P3 findings, each inline.
- [P2] No CI job runs the two new test files.
docs/fern/scripts/tests/test_relink_shared_reference.py:25 - [P3] No test covers the
reference/generalscope check inrelink().docs/fern/scripts/tests/test_relink_shared_reference.py:37 - [P3] No script makes or checks the 984 new redirects.
docs/fern/docs.yml:50
Open items:
- The thread at
docs/fern/docs.yml:648is still open. This review agrees with the answer there and replied with the HTTP status codes. - The
PRrun 39289336058 onpull-request/16792still runs one job,dynamo-runtime / test / gpu cuda13.0, amd64. Its other jobs: 60 passed and 23 skipped.
What this review measured on 54f5dc7.
Redirects. The 984 new entries sit at the top of redirects:, and the 556 old entries follow them unchanged. No source appears twice, and no source is the same as an old exact source. On docs.nvidia.com today, every source is dead:
| what the source answers today | sources |
|---|---|
| 404 | 370 |
200 with the "Page Not Found" text (Fern answers a missing .md or .mdx path this way) |
591 |
| 308 through an old pattern rule, to a page that is also gone | 23 |
This count matches the 23 in the description. Today these sources go through /dynamo/blog/:slug*, /dynamo/recipes/:slug* and /dynamo/dev/backends/:slug*. Of those targets, 14 answer 404 and 9 answer the "Page Not Found" text.
Order of the rules. On the live site, an exact rule wins over an earlier pattern rule. Old entries 63 and 77 show it for /dynamo/dev/knowledge-base/modular-components/ai-simulate/spica/overview, and old entries 389 and 390 for /dynamo/dev/user-guides/custom-backend. So the new entries win at any place in the list, and the place at the top does no harm.
Destinations. Of the 311 different internal destinations, 300 answer 200. The other 11 land on a page that answers 200 after one more redirect. Six of these are section or version slugs with a 307, for example /dynamo/v1.1.1/backends. Five go through an old rule, for example /dynamo/digest/flash-indexer. Of the 273 different GitHub destinations, 255 name a tag and 18 name main, and git ls-tree finds every path at its ref. 34 versioned sources point at a later tag, and in each case the file does not exist at the source's own tag. A sample of 20 GitHub destinations answered 200, and a missing file answered 404.
Scripts. The 16 new tests pass at the head, and on the merge with main at fc765f7e60a9d151322fddf8a11bddca57717cc6. The whole docs/fern/scripts/tests folder passes at the head (225 tests). The new href tests fail on the old resolver. Deliberate breaks that drop the anchor, skip the href rewrite, or rewrite an href inside inline code each fail a test. The fourth break is the P3 at line 37.
Simulation. simulate_docs_website.sh passes all assertions at the head. It relinks 17 snapshot files and leaves 0 relative translated links. On the composed tree, fern docs broken-links finds 372 errors without the relink step and 322 with it. The relink removes 50 errors, adds none, and leaves none in the new snapshot.
Workflows. On a tag push, the job runs the workflow file of the tag, and github.sha is the tagged commit. So the step and the script always come from one commit. On workflow_dispatch, github.sha is the tip of the branch that starts the run. A force_rebuild of an older tag from main uses the script from main. The sparse checkout is enough, because the script imports only the standard library.
--strict. This review used Fern CLI 5.80.2, the version that fern.config.json pins and that CI used. On main at 3e3794072b931c385cc61ecbebff81ad1440ec63, the plain command exits 0 with 1 error, and --strict exits 1. At the head and on both merges, --strict exits 0. The check does not test external links. This review planted a link to a host that does not exist and a link to a missing GitHub file. Neither gave an error, and the command opened no connection to either host. So a slow or down outside site cannot fail pre-merge.
Page edits. Every changed link resolves. The relative targets exist and are in index.yml. The GitHub targets exist on main and are not in the nav, which agrees with the author's answers on the two resolved threads. /dynamo/dev/recipes/inkling answers 200. From the folder of the English page, the five new zh-CN image paths resolve to files under docs/fern/assets/img. On the live site, the dev zh-CN pages show these images with a raw relative src. The v1.3.0 zh-CN pages use the English-relative form, and Fern serves their images from /dynamo/_fern-img/ and /dynamo/_fern-files/. This review did not request the new NGC catalog URL. It matches the 11 other NGC container links in the repo.
Merge. The head merges with main at fc765f7e60a9d151322fddf8a11bddca57717cc6 with no conflict. Since the merge base, main changed some docs files but added, moved or deleted no page, and it did not change index.yml or docs.yml. So no redirect destination changed.
CI on the head: Pre Merge 39289332435, Fern Docs 39289334734, Docs link check 39289332363, PR-XPU 39289335702, codeowners, Copyright Checks, DCO Commenter, Lint PR and PR Issue Link passed. Request NVSkills CI and Trigger CI Approval Flow were skipped. Recipe Check in Pre Merge was skipped.
- Add test_relink_shared_reference.py and test_resolve_translation_links.py to the api-docs pytest list; no job collected them before. - Give the relink fixture a shared file outside reference/general/ so the scope check is covered. - Name how the exact redirect entries in docs.yml were found and mapped. Signed-off-by: Dan Gil <dagil@nvidia.com>
dmitry-tokarev-nv
left a comment
There was a problem hiding this comment.
Reviewed head 54f5dc7d4f3c92089c85ebc53f6fa26894c56394. No P0 or P1 is open. One P2 and two P3 from this review stay open, and each has an inline comment with a tested fix or a clear ask.
The 984 redirects are sound. Every source is dead on docs.nvidia.com today, every internal destination ends on a live page, and every GitHub destination exists at its ref. The relink and the href resolver work end to end in simulate_docs_website.sh. fern docs broken-links --strict passes on the head and on the merge with main, and it checks no external links. The merge with main is clean.
Open items are the P2 and the two P3 findings. The P2 is that the two new test files run in no CI job. The thread at docs/fern/docs.yml:648 is also open, and the author's answer there is correct. At 19:45Z, the PR run 39289336058 still ran one GPU job. Every other run on the head passed, except three bot runs that were skipped.
dmitry-tokarev-nv
left a comment
There was a problem hiding this comment.
Reviewed head 54f5dc7d4f3c92089c85ebc53f6fa26894c56394. No P0 or P1 is open. One P2 and two P3 from this review stay open, and each has an inline comment with a tested fix or a clear ask.
The 984 redirects are sound. Every source is dead on docs.nvidia.com today, every internal destination ends on a live page, and every GitHub destination exists at its ref. The relink and the href resolver work end to end in simulate_docs_website.sh. fern docs broken-links --strict passes on the head and on the merge with main, and it checks no external links. The merge with main is clean.
Open items are the P2 and the two P3 findings. The P2 is that the two new test files run in no CI job. The thread at docs/fern/docs.yml:648 is also open, and the author's answer there is correct. At 19:45Z, the PR run 39289336058 still ran one GPU job. Every other run on the head passed, except three bot runs that were skipped.
⏹️ Dynamo PR CI cancelled — run 39317071073 (attempt 1) on
|
| Other | Jobs |
|---|---|
| dynamo-runtime | ⏹️ 1 ✅ 7 |
Failure details
No jobs failed. 1 job was cancelled: dynamo-runtime / rust-gpu hung for ~30 min in Initialize containers on the self-hosted runner and was then cancelled. That is a runner/infrastructure problem, not a fail-fast cancel, and rerunning the failed jobs will probably clear it.
⏹️ dynamo-runtime / rust-gpu: custom container implementation failed (runner infra)
Job: dynamo-runtime / rust-gpu · Failed step: Initialize containers · Logs: gh api repos/ai-dynamo/dynamo/actions/jobs/118282912029/logs
Velonix runner admission allowed repository=ai-dynamo/dynamo event=push ref=refs/heads/pull-request/16792
##[group]Run '/home/runner/k8s-novolume/index.js'
##[error]Executing the custom container implementation failed. Please contact your self hosted runner administrator.
Cleaning up orphan processes
The k8s container hook on the self-hosted GPU runner failed while initializing the job container (20:13 to 20:44 UTC), so no build or test steps ran. Runner infrastructure problem; a rerun of failed jobs is likely enough.
For agents
{"pr": 16792, "run_id": 39317071073, "run_attempt": 1, "head_sha": "ef997ef1d4ce02cf5f2f79b2cdf5b40b2c95b6bb",
"failures": [{"job": "dynamo-runtime / rust-gpu", "job_id": 118282912029, "conclusion": "cancelled", "failed_step": "Initialize containers", "signature": "Executing the custom container implementation failed (runner infra)", "tests": [], "log_cmd": "gh run view --job 118282912029 -R ai-dynamo/dynamo --log-failed"}]}Posted automatically by Devin for run 39317071073. Updated on every full-CI run of this PR.
akshatha-k
left a comment
There was a problem hiding this comment.
Thanks for this. It fixes the link the VDR called out, and the broad redirect work looks sound.
What I verified
- The VDR's broken Quickstart "Release Artifacts" link points at
/dynamo/reference/general/release-artifacts.mdx, which is a Page Not Found on the live site. The new exact redirect sends it to/dynamo/reference/release-artifacts, which loads. The same fix is applied for v1.4.0 to v1.5.1 and zh-CN. - The other links cited in the VDR (router, multimodal, DGDR walkthrough, Qwen3 recipe, deprecations,
tool-call-parsing.mdxat v1.5.0) already resolve, so nothing was needed there. - I checked out this branch and ran
fern docs broken-links --strict. It passes. I created placeholder files for the 11 generated API-reference pages, because the API generators need Python 3.11+ and I only had 3.9. - I served the branch with
fern docs devand tested the literal internal redirect destinations (wildcard:slugrules excluded). All 23 unversioned destinations load, and 205 of 218/dynamo/dev/...destinations load.
Redirect destinations that don't resolve in my local build [However, they do run when checking manually on the live fern preview. Requesting we double- check once the fern docs are published]
These returned Page Not Found in my local fern docs dev build. To confirm once the docs page is live, since the two may differ. Paths are under /dynamo/dev/ unless noted.
Destinations where I found the real page:
knowledge-base/design-documents/fault-tolerance/fault-tolerance-testing- Real page:
knowledge-base/concepts/fault-tolerance/fault-tolerance-testing
- Real page:
knowledge-base/design-documents/fault-tolerance/request-cancellation-architecture- Real page:
knowledge-base/concepts/fault-tolerance/request-cancellation-architecture
- Real page:
knowledge-base/design-documents/disaggregated-serving- Real page:
knowledge-base/concepts/system-architecture/disaggregated-serving
- Real page:
zh-CN/dev/knowledge-base/design-documents/disaggregated-serving- Real page: same as the one above
knowledge-base/concepts/simulation/ai-simulate/sweeper/glm-5-fp8-pareto-sweep- Real page:
.../sweeper/glm-5-fp-8-pareto-sweep(the slug hasfp-8)
- Real page:
kubernetes/kv-aware-routing/gateway-api- Real page:
reference/components/gateway-api-routing
- Real page:
reference/api/kubernetes/additional-resources/api-reference-k8s- Real page:
reference/api/kubernetes/full-api-reference
- Real page:
kubernetes/installation/observability- Real page:
cli/operations/observability
- Real page:
Destinations where I found no matching page:
knowledge-base/design-documents/architecture-flow(concepts/architecturemay be the successor)knowledge-base/design-documents/distributed-runtimeknowledge-base/design-documents/communication-planes/discovery-planeknowledge-base/design-documents/communication-planes/event-planeknowledge-base/design-documents/communication-planes/request-planekubernetes/fault-tolerance/introduction
dmitry-tokarev-nv
left a comment
There was a problem hiding this comment.
Reviewed head ef997ef1d4ce02cf5f2f79b2cdf5b40b2c95b6bb. No P0 or P1 found. This review has one P3 finding, inline.
- [P3] The new comment above
redirects:does not say that 34 GitHub entries point at a later tag ormain.docs/fern/docs.yml:54
The one P2 and two P3 findings from the review on 2026-10-19 are fixed at this head. Each of those threads has a reply with the measurement.
Open items:
dynamo-status-checkfailed in thePRrun 39317071073. The cause is thatdynamo-runtime / rust-gpuwas cancelled atInitialize containers, beforeCheckout repository. No code ran in that job, so the failure is not related to this diff.- The 14 destinations in the review from akshatha-k come from redirect entries that are already on
main. None of the 984 new entries names them.
What this review measured on ef997ef.
Delta. ef997ef is one commit on top of 54f5dc7, with no force push. It changes the api-docs step in pre-merge.yml, the comment above redirects: in docs.yml, and the fixture in test_relink_shared_reference.py. The 1540 redirect entries are the same as at 54f5dc7.
Tests. The api-docs test step runs 225 tests at the head and on the merge with main, and all pass. Pre Merge run 39317065671 ran the same 225 tests, and all passed. These deliberate breaks of the new code each fail a test at the head:
| break | at ef997ef | at 54f5dc7 |
|---|---|---|
relink() drops the #anchor (the api-docs step) |
1 failed, 224 passed | 209 passed |
relink() loses the reference/general scope check (the relink tests) |
1 failed, 8 passed | 9 passed |
the translation resolver skips the href rewrite (the api-docs step) |
2 failed, 223 passed | not run |
Docs checks. simulate_docs_website.sh passes all assertions at the head and on the merge. fern docs broken-links --strict with Fern CLI 5.80.2 passes at the head and on the merge. It fails on main with 1 error for deepseek-v4-pro, and it fails on a planted broken link with 2 errors.
Merge. The head merges with main at 649bc1469578aeeecc30099ce706185e917479d1 with no conflict. Since the merge base, main added one page to index.yml. No redirect names that page. The head also merges with the newer tip 4ee36793506dee95b4c654cf281bdfaea1c423b0 with no conflict. Its two new commits change only Rust files under lib/ and Cargo.lock.
CI on ef997ef. Pre Merge 39317065671 passed, with Recipe Check skipped. Fern Docs 39317070517 passed, with the release job skipped. Docs link check, codeowners, Copyright Checks, DCO Commenter, Lint PR, Label PR and PR Issue Link passed. PR-XPU 39317070840 skipped changed-files, xpu-ci-vllm and xpu-status-check. In the PR run 39317071073, 61 jobs passed and 23 were skipped. dynamo-runtime / rust-gpu was cancelled, and dynamo-status-check failed. The two Request NVSkills CI runs and Trigger CI Approval Flow were skipped.
| # version's tag when the target is not a nav page. Kept above the pattern | ||
| # rules, which would otherwise send some of these to pages that are also gone. |
There was a problem hiding this comment.
[P3] The new comment says that a GitHub entry points at the version's tag. But 34 entries point at a later tag or main, because the file is missing at that tag. docs/fern/docs.yml:54. Please name this fallback, so that a maintainer who extends the list does not link to a missing file.
| # version's tag when the target is not a nav page. Kept above the pattern | |
| # rules, which would otherwise send some of these to pages that are also gone. | |
| # version's tag when the target is not a nav page. When that tag lacks the | |
| # file, the entry uses a later tag or main that has it. Kept above the | |
| # pattern rules, which would otherwise send some of these to pages that are | |
| # also gone. |
Measured on ef997ef, with controls.
This review compared the ref of each GitHub destination with the version in its source path. It used git cat-file -e <ref>:<path> in a clone of this repository.
| GitHub entries with a versioned source | entries |
|---|---|
at the tag of the source version (main for dev) |
499 |
| at a later tag | 26 |
at main |
8 |
For each of the 34, the file is missing at the tag of the source version. The file is present at the ref that the entry names. Five entries at their own tag are present there, and a made-up path is missing. Two examples:
/dynamo/v1.0.2/deploy/snapshot/cmd/snapshotctl/README.mdgoes tov1.1.0./dynamo/v1.2.1/components/src/dynamo/thunderagent_router/README.mdgoes tomain.
The comment also does not describe 74 internal entries that go to a page in another version, and 4 that go to the other language. This review did not find out why, so the suggestion covers only the tag fallback.
With the suggestion applied, these pass: the api-docs test step (225 passed), fern check (0 errors), and fern docs broken-links --strict. The codespell, check-yaml, trailing-whitespace, mixed-line-ending and check-merge-conflict hooks pass at the versions that .pre-commit-config.yaml pins. The parsed docs.yml is the same as at the head.
… versions (ai-dynamo#16792) Signed-off-by: Dan Gil <dagil@nvidia.com>
Summary
reference/generalcopies in favor of the sharedpages-devfiles, but links inside the snapshot still named the dropped copies. A newrelink_shared_reference.pystep points them at the shared copies.hreftargets in translated pages to site URLs, as Markdown links already are, so the zh-CN quickstart cards land on published pages. The release job runs the relink script from the workflow's own revision, so rebuilding an older tag still finds it.fern docs broken-linkscheck with--strict. Without it the command reports errors and still exits 0, so the job could never fail.Validation
python3 -m pytest docs/fern/scripts/tests- passdocs/fern/scripts/simulate_docs_website.sh- all assertions pass, including 0 relative translated links (Markdown andhref) in the dev and tag mirrors;fern check0 errors on the composed treefern check- 0 errorsfern docs broken-links --strict- all checks pass (mainreports 1 broken link, fixed here)python3 docs/fern/scripts/docs_lint.py- 0 errorsRefs: DYN-5011