ci: check documentation links on PRs and nightly with a shared cache

[rwgk]

Summary and narration

This PR completes the workflow changes for replacing pre-commit.ci with GitHub Actions, following the direction in #2652. #2994 already introduced the standalone Linux and Windows pre-commit checks and monthly Dependabot hook updates. This PR gives documentation link checking its own Linux workflow and connects it to the existing nightly workflow.

The main change is when link checking can run. Previously, checking rendered documentation was a step in the wheel-based documentation build reached through ci.yml. The new workflow runs directly on PR updates, so it can check the proposed documentation without waiting for copy-pr-bot, wheel builds, or GPU CI. It checks both the documentation we write and the HTML that Sphinx generates. Building that HTML matters: generated API pages, cross-package references, and anchors need to be checked in the assembled documentation, beyond what the local pre-commit hook sees in checked-in Markdown and reStructuredText.

PR runs check GitHub's test-merge revision, including the changes from both the PR and its base branch. Each run builds fresh HTML and checks local files, anchors, and canonical page links against that build. New pages can therefore pass before they are published, while missing pages still fail. Nightly runs use the same checker, check links afresh, and publish successful external-link results that subsequent PR runs can reuse for up to one day.

The checker also gives recognized temporary HTTP failures time to recover. When those are the only remaining failures, it waits and tries again using the successful results already cached, with a limit of ten passes including the first. A site returning HTTP 429 can recover without requiring us to rerun an entire workflow or repeat requests that have already succeeded. A broken link or unclassified error stops additional passes immediately, and a temporary failure that persists through the limit still fails the check.

The existing wheel-based documentation build and preview deployment stay in place. They exercise the documentation built from CI's wheels; the independent workflow exercises documentation built from the checked-out sources. Lychee moves out of build-docs.yml, and the old Windows pre-commit job moves out of ci.yml, since #2994 already supplies its replacement. This avoids repeating those checks when the PR is copied to pull-request/<number> for full CI.

Merging this PR completes the workflow implementation. The administrative cutover follows separately: require the three replacement checks, remove the old pre-commit.ci requirement, then revoke pre-commit.ci's access to cuda-python under Settings > Integrations > GitHub Apps.

The expandable sections below cover the implementation for reviewers, the validation evidence, and the exact Rulesets changes for that cutover.

Details for all reviewers

How the workflows fit together

Entry point	What runs
PR opened, reopened, or updated	The standalone Linux/Windows pre-commit workflow from #2994 and the new Linux documentation-link workflow. Draft and fork PRs are included, subject to GitHub's normal fork-workflow approval settings.
Push to copy-pr-bot's pull-request/<number> ref	Existing full CI, including wheel-based documentation rendering and preview deployment. The replacement workflows have no push trigger for these refs.
Existing nightly schedule	The reusable documentation-link workflow, with a fresh link sweep and cache publication, alongside the existing nightly suite.
Manual workflow dispatch	Run the checker in cache-reader or cache-refresh mode, or exercise the nightly integration in documentation-only mode.

The direct PR checks run independently of /ok to test and a [no-ci] PR title. The workflow triggers have no path filters, so their required-check names can be reported for every PR update. Superseded runs are cancelled within the same PR and mode; manual cache modes and nightly test modes have separate concurrency groups.

What the new checker validates

.github/workflows/lychee.yml runs two independent jobs, Lychee (authored) and Lychee (rendered), followed by the aggregate Documentation links check. The authored job checks tracked .md and .rst files outside qa/, skipping symlinks. The rendered job checks HTML throughout the assembled cuda-python, cuda-bindings, cuda-core, and cuda-pathfinder documentation, excluding _static assets and enabling full fragment validation.

Checkout uses the default revision for the triggering event. For a PR, that is GitHub's test merge with its base branch, matching the standalone pre-commit workflow. This catches integration problems such as a PR linking to a page that was removed on the base branch. Manual and nightly runs check their selected branch revision. Generated GitHub source links use the actual checked-out SHA, including the merge SHA for PR runs. The checkout retains Git history and tags for SCM-derived versions.

The source-build helper is exposed as docs-build-all-latest in cuda_core's Pixi manifest. It uses the existing locked docs environment and local source dependencies. It verifies that the three sibling libraries import from this checkout and agree with their distribution metadata, installs the metapackage with --no-deps to retain those dependencies, and uses the existing documentation scripts to assemble all four latest trees under artifacts/docs.

For this checking build, the helper sets CUDA_PYTHON_DOCS_DOMAIN to the absolute file:// URI of artifacts/docs. Sphinx's canonical links therefore resolve to the local rendered pages, including pages that have not been published yet. The checker validates those targets rather than excluding them or expecting the production site to contain the PR's new pages. This override is confined to the source build used for link checking; the wheel-based documentation build and published canonical URLs keep their existing configuration. Existing URL exclusions in lychee.toml are unchanged.

Input selection produces deterministic absolute-path lists, preserves spaces, and rejects empty lists or filenames containing line breaks. Its tests cover those cases and the authored/rendered selection rules. The workflow uses Python 3.14, hosted Linux runners, read-only repository permissions, and checkout without persisted credentials. Lychee stays pinned to v0.24.2, matching the local hook.

Cache behavior and failure handling

The cache contains link-check results. PR runs restore the newest accessible matching snapshot and do not publish one. Nightly runs skip restoration, check afresh, and publish a new immutable snapshot keyed by run ID and attempt. Authored and rendered checks have separate namespaces incorporating the Lychee version and a hash of the checking policy. Documentation edits retain reusable external-link results, while a policy change selects a new namespace.

Successful external checks expire after one day. Lychee v0.24.2 omits failed responses from its persisted cache and does not cache filesystem checks. A nightly sweep can publish its successful results even when some URLs fail; the failing URLs are checked again on the next run. Local files, canonical targets, and anchors are checked against the fresh build each time.

After merge, nightly's main-scoped snapshots can supply a common baseline to PRs, including fork PRs. Manual branch refreshes stay within their branch's cache scope. This follows GitHub Actions' cache access rules; it does not create a globally writable cache shared by PRs.

The existing rendered-check throttling and retries are retained: 16 concurrent requests overall, two per host, a 250 ms host request interval, three retries, and a 30-second request timeout. Both jobs reject empty input and require an explicit successful checker result. Documentation links runs even if a dependency fails and requires both link-check jobs to succeed. Reports are available in job summaries and as seven-day artifacts.

Bounded retries within each job

The retry helper reads Lychee's JSON report and retries only when every remaining failure is a recognized transient HTTP(S) failure: status 408, 429, or 5xx, or an HTTP(S) timeout. A 404, missing local file, invalid anchor, unclassified error, or a mixture of temporary and permanent failures stops additional passes immediately.

The initial action pass counts toward a maximum of ten complete link-check passes. For an eligible failure, the helper waits 60 seconds before the second pass and 120 seconds before each subsequent pass. Every pass uses the same pinned binary, input list, configuration, request limits, token, and .lycheecache. Successful external checks remain cached; unsuccessful checks and local files are checked again. This adds a cooldown between passes while retaining Lychee's existing per-request retries.

Nine cooldowns total 17 minutes, leaving 43 minutes of the 60-minute job limit for setup, the documentation build, and all checking passes. Earlier measurements were about seven minutes for the build, five minutes for a cold rendered check, and 40-60 seconds per retry during a persistent HTTP 429. Even nine one-minute retries give about 38 minutes including cooldowns, plus setup; an actual job completed all ten attempts in about 37 minutes. The attempt limit and the overall time limit are complementary safeguards.

The action's first pass uses fail: false so the helper can handle its result. Its Markdown-only empty-report guard is also disabled for JSON output; the helper requires a positive checked-link count and validates the counts, failure-map shape, and agreement with the CLI exit code. Exit code zero with no reported failures is required for success. Setup, configuration, argument, missing-report, and malformed-report failures stop immediately. Neither exhausting the retry limit nor disabling the action's initial guard can turn an unsuccessful checker result into a passing job.

Every attempt's JSON report is retained as an artifact. The helper produces a readable Markdown summary with attempt exit codes and the final counts and failure details, and publishes it in the job summary and artifacts. A recovered error remains visible in earlier reports without appearing as the current result. The retry tests cover transient classification, mixed failures, recovery, exhausted retries, cache and argument reuse, non-link failures, JSON validation, and the attempt limit. The helper is included in the cache-policy hash so changes to this behavior select a new baseline namespace.

Integration and contributor impact

ci.yml removes the duplicate Windows pre-commit job and its gate dependency. build-docs.yml removes the embedded Lychee and cache steps. ci-nightly.yml calls the reusable checker independently of wheel discovery and requires its success in the nightly status gate. Its documentation-links-only mode also runs the standalone CI-tool tests and verifies that wheel/GPU jobs remain skipped.

The standalone pre-commit.yml also carries forward #3000's explicit Windows symlink setup before checkout, restricted to the Windows matrix job. This preserves that configuration when the old job is removed.

Check job status continues to summarize heavyweight CI's own jobs. The independent pre-commit and documentation checks become merge requirements through Rulesets, as described below. This follows the existing pattern of requiring the independently triggered PR metadata check.

For contributors, pre-commit install and pre-commit run --all-files retain their existing roles. Local Lychee still checks authored documentation. CONTRIBUTING.md describes the Actions checks and keeps the hook-installation reminder focused on developer machines. Per-host local caching remains a follow-on that requires a stable Lychee release with --cache-location; coordinated version updates remain necessary across the hook revision, hook argument, and CI pin.

Validation and full CI coverage

Validation at the reviewed revision

The reviewed PR head is 081ded4, based on main at 4c893de. The direct PR documentation checks verified GitHub's test-merge revision 692e123; both job checkout logs confirm that SHA. The evidence below supersedes the earlier runs from before the canonical-link and merge-checkout fixes. All focused checks passed. At the last check, full CI had 104 successful jobs and two A100 jobs still queued, with no failures; the final status gate had not yet run.

Evidence	Result	What it covers
Direct PR documentation checks	Passed on workflow attempt 1	Actual PR merge checkout, source documentation build, local canonical targets, rendered links and fragments, authored inputs, reports, and the aggregate Documentation links gate.
Standalone pre-commit	Passed	Linux and Windows hook execution, including Windows symlink setup and formatting/linting of the changed files.
Lockfile freshness and Pixi source builds	Passed	The locked environments remain consistent with their manifests, and package source builds remain healthy.
Full CI	Pending at last check: 104 jobs passed, 2 queued	The full build/test plan on pull-request/2993, wheel-based documentation rendering and preview deployment without embedded Lychee, package builds/tests, and Check job status.
Nightly documentation-only producer	Passed on workflow attempt 1	The reusable nightly call, fresh link checking, cache publication, CI-tool tests, the nightly status gate, and expected skipped wheel/GPU jobs.
Cache-reader mode	Passed on workflow attempt 1	Restoration of the producer's exact authored and rendered caches, successful checking, and skipped cache publication.

All three direct PR jobs passed. Neither link job found a matching saved cache, and both passed on their first checker attempt. Authored checking covered 693 occurrences of 468 unique links; rendered checking covered 740,786 occurrences of 12,449 unique links. Both reports contain zero errors and timeouts. The rendered build took 6 minutes 42 seconds and link checking took 2 minutes 47 seconds. This is actual PR-event coverage of the merge checkout and generated GitHub source links, in addition to the separate local regression cases below.

The nightly documentation-only run completed five jobs successfully and intentionally skipped wheel discovery plus 11 GPU or optional-dependency jobs. Both link jobs passed on their first checker attempt and published separate authored and rendered caches with keys ending in baseline-37524743899-1. Its CI-tool job passed all 169 tests and 36 subtests.

The cache reader passed all three jobs on its first workflow attempt, with both link jobs passing on their first checker attempt. Its logs confirm that it restored the exact two producer snapshots and skipped cache publication. Both final reports contain zero errors and timeouts. Rendered link checking took about 22 seconds using that cache, compared with about 160 seconds in the fresh producer; the reader still built its own documentation and checked local files and anchors. Authored checking took about 0.02 seconds, compared with about 134 seconds in the producer.

Full CI's wheel-based documentation build and preview deployment both passed. These exercise the existing publication path after moving Lychee to its own workflow. At the last check, the run was on workflow attempt 1 with no failures or reruns. Two A100 jobs using local builds remained queued: Python 3.10 with CUDA 12.9.1, and Python 3.14 with CUDA 13.4.2. The overall run and final Check job status gate were still pending.

The full CI run exercises the existing build, test, and documentation integration. Direct PR checks exercise the link checker that intentionally runs outside full CI, while the focused nightly/cache runs exercise the reusable call and snapshot paths. Local regression and failure-path tests cover the errors that must keep a check red. Check job status reports the heavyweight CI result; the independent Documentation links result remains a separate requirement.

The producer/reader sequence tests real cache publication and reuse within the PR branch's scope. Default-branch warming and reuse by other PRs can be verified after merge by running nightly on main and then checking a PR. The administrative cutover likewise requires successful actual PR checks after merge.

Local regression and failure-path checks

Local validation used Pixi 0.81.0 already on PATH with Python 3.14.7. All 169 standalone CI-tool tests and 36 subtests passed, and full pre-commit run --all-files passed. The two new build-helper regression cases exercise its actual environment setup and artifact copy for checkout paths with and without spaces, verifying that the final output URI overrides an inherited production domain. These small tests stub package installation and documentation rendering; the following checks separately exercise real Sphinx and Lychee.

For the new-page regression, a real build of all four documentation trees included two temporary new cuda-core pages, with a link from one to the other. All 1,118 generated canonical links resolved to the local output. With external network requests disabled, pinned Lychee passed the new-page check and a complete local-file and anchor scan of the rendered tree. Removing the new target then produced a missing-file failure and exit code 2. The temporary pages were removed after testing. The hosted runs above separately provide external-link coverage.

A separate temporary Git repository exercised the merge-coverage gap: the PR branch added a link to an existing file, while main independently removed that file. The branches merged without a Git conflict. Pinned Lychee passed at the PR head and failed with a missing-file error at the merge revision. This demonstrates the failure missed by a head-only check; the successful direct PR run above additionally verifies GitHub's actual merge checkout and its generated source links.

The retry tests cover HTTP 408/429/5xx and timeout classification, immediate stopping for permanent or mixed failures, recovery, exhaustion at ten total attempts, argument and cache reuse, non-link failures, malformed or missing JSON, count/map inconsistencies, and disagreement between exit codes and reported failures.

Earlier deterministic checks of the unchanged retry helper used the pinned Lychee binary against a localhost HTTP server: a 429 response recovered on the second pass with successful checks reused from cache, while a 404 stopped after the first pass. Earlier hosted nightly failures exhausted ten passes on a persistent Conda HTTP 429 and kept the job and aggregate gates red. These observations explain the failure behavior and timing budget; they are separate from the current revision's validation above.

Reproducing the focused checks

For the same source documentation build on Linux:

PIXI_LOCKED=true pixi run --manifest-path cuda_core/pixi.toml -e docs docs-build-all-latest

For hosted testing, select the PR branch explicitly and first run the nightly integration in documentation-only mode. It performs a fresh link check and publishes branch-scoped caches:

gh workflow run ci-nightly.yml --repo NVIDIA/cuda-python --ref rwgk/maint/lychee-pr-nightly -f documentation-links-only=true

Wait for that run to finish successfully and confirm that both cache snapshots were saved. Then run the reader on the same branch and confirm that its restore logs name those producer keys:

gh workflow run lychee.yml --repo NVIDIA/cuda-python --ref rwgk/maint/lychee-pr-nightly -f refresh-cache=false

The nightly documentation-only run already exercises the refresh path through its reusable call. Manual runs validate workflow execution at the selected branch revision; actual PR runs additionally exercise the test-merge checkout and supply the checks needed for the Rulesets cutover.

Details for admin updating the Rulesets

What changes, and why

The workflows report their results; Rulesets decide which results are required for merging. The current Prevent committing without PR ruleset requires pre-commit.ci - pr, Check job status, and PR has assignee, labels, and milestone. It applies to main, 12.9.x, 11.8.x, 13.4.x, and release/**/*.

Add the three replacement requirements in a new main-only Ruleset, then remove the old pre-commit.ci requirement from the shared Ruleset. This limits the new requirements to the branch containing the replacement workflows. GitHub combines applicable Rulesets, so main will have five required check contexts across the two Rulesets. This is a one-time manual cutover; the helper preserved in closed #3002 is not needed.

Cutover steps

1. Verify the replacement before changing requirements. After ci: check documentation links on PRs and nightly with a shared cache #2993 is merged, confirm that pre-commit.yml and lychee.yml are on main. Obtain successful Pre-commit (Linux), Pre-commit (Windows), and Documentation links checks on the current commit of a representative PR targeting main. Use its actual pull_request runs, including a green rerun of any failed check. GitHub evaluates required checks on the latest commit, and manually dispatched workflow jobs do not satisfy PR requirements. Keep pre-commit.ci installed and required during this verification. Required-check guidance

2. Create the additional main-only Ruleset. In repository Settings, open Rulesets, then New ruleset > New branch ruleset. Name it, for example, Main pre-commit and documentation checks, set enforcement to Active, and target only the exact branch main. Enable Require status checks to pass before merging and add Pre-commit (Linux), Pre-commit (Windows), and Documentation links. Select GitHub Actions as the expected source for each, rather than any source; its App integration ID is 15368. Match the existing status-check policy: leave Require branches to be up to date before merging unchecked and keep branch creation exempt. Leave the bypass list empty and enable only the status-check rule. Save the Ruleset. Creating a Ruleset and choosing the expected check source

3. Remove the retired requirement from the existing Ruleset. Edit Prevent committing without PR and remove only pre-commit.ci - pr from its required checks, then save. Its old App integration ID is 68672. Preserve the other two checks, branch targets, review requirements, and all other protections. Creating the new requirement first keeps main protected throughout the transition.

4. Confirm the effective merge requirements. A PR targeting main should now show the five checks listed below as required, all from GitHub Actions, with no pre-commit.ci - pr requirement. On a temporary test PR, introduce a formatting or documentation-link error, verify that the corresponding required check fails and blocks merging, then repair it and verify success. Confirm the required-check result in the merge box; a PR being blocked merely because it is draft is not proof of enforcement. The release branches covered by the shared Ruleset retain their existing two Actions requirements; they do not gain the three new checks until the workflows are deliberately backported.

5. Retire pre-commit.ci for cuda-python. After the required-check verification, open repository Settings > Integrations > GitHub Apps, choose Configure for pre-commit.ci, and remove only cuda-python from its selected repository access, then save. This opens the NVIDIA installation's settings, which also control access to other repositories. Preserve their access. If the installation currently covers All repositories, coordinate with an organization owner to retain the other repositories when changing to selected access. Use repository access rather than suspending or uninstalling the shared installation. App repository-access instructions

Expected result on main

Required check	Ruleset	Expected source
Check job status	Existing shared Ruleset	GitHub Actions
PR has assignee, labels, and milestone	Existing shared Ruleset	GitHub Actions
Pre-commit (Linux)	New main-only Ruleset	GitHub Actions
Pre-commit (Windows)	New main-only Ruleset	GitHub Actions
Documentation links	New main-only Ruleset	GitHub Actions

For an optional read-only confirmation of the effective requirements:

gh api repos/NVIDIA/cuda-python/rules/branches/main --jq '.[] | select(.type == "required_status_checks") | .parameters.required_status_checks[] | {context, integration_id}'

The final output should contain the five contexts above, each with integration ID 15368. Rule editing requires repository admin access or permission to edit repository rules; changing the organization's App installation may require additional installation-management access.

[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.

[rwgk]

EDIT: The links below are outdated, but the guidance in general is still useful.

I asked codex to guide me through reviewing this PR myself. Sharing what it gave me (in part because I want to click the links here myself):

Review Files changed against #2994; that isolates this layer. I’d use six passes, each with one question to answer before moving on.

1. When does it run, and what does it check?
   Start with lychee.yml’s triggers and checkout. Trace a PR update, nightly call, and manual run. There is no push trigger, so copy-pr-bot’s branch pushes do not add another run. Checkout selects the PR’s head SHA.

2. Are we selecting the intended documentation?
   Read the input selector, then its tests. Authored inputs are tracked Markdown/reST outside qa/; rendered inputs are HTML outside _static. Pay particular attention to skipping README symlinks: checking the same content from another directory can misinterpret relative links. Empty inputs must fail.

3. Does rendered checking use this PR’s sources?
   Follow the build helper. The important safeguards are verifying that all three libraries import from the checkout and match their installed metadata. Installing metapackage metadata with --no-deps preserves those local packages.

4. Does caching preserve the checking policy?
   Read cache preparation through publication. Trace both values of refresh-cache: PRs restore; nightly checks afresh and publishes. Version, policy, and authored/rendered kind separate the namespaces; successful URL checks expire after one day. Shared visibility relies on publishing from main, under GitHub’s cache scope rules.

5. Can failures accidentally produce a green check?
   Examine the checker and aggregate gate, then the nightly gate. Think through a failed docs build, one failed matrix leg, cancellation, and documentation-only mode. That mode requires successful link/tool checks and skipped wheel/GPU jobs.

6. Do the deletions have complete replacements?
   Finish with build-docs.yml, ci.yml, and the documentation changes. The dedicated workflow replaces inline lychee; [no-ci] ci: run pre-commit on Linux and Windows with Dependabot hook updates #2994 replaces Windows pre-commit. Live required-check migration belongs to ci: add required-check migration helper #3002.

[rwgk]

/ok to test 27b3cf9

[github-actions]

Doc Preview CI
🚀 View preview at https://nvidia.github.io/cuda-python/pr-preview/pr-2993/
https://nvidia.github.io/cuda-python/pr-preview/pr-2993/cuda-core/
https://nvidia.github.io/cuda-python/pr-preview/pr-2993/cuda-bindings/
https://nvidia.github.io/cuda-python/pr-preview/pr-2993/cuda-pathfinder/
Preview will be ready when the GitHub Pages deployment is complete.

[rwgk]

/ok to test ed21592

[rwgk]

/ok to test d15a151

[mdboom]

From my agent. If true, this seems pretty serious -- it means all new internal links added to the docs would fail the lychee test. We can test whether it is correct by adding a new page to the docs and a link to it.

The script builds with BUILD_LATEST=1 and BUILD_PREVIEW=0. I checked how that plays out in the doc configs and lychee:

cuda_core/docs/source/conf.py and cuda_python/docs/source/conf.py set html_baseurl to https://nvidia.github.io/cuda-python/<pkg>/latest/ when BUILD_LATEST=1. Sphinx emits <link rel="canonical"> from it on every page.
Lychee 0.24.2 only skips preconnect and dns-prefetch link rels (html5ever.rs:179-182), so canonical URLs are extracted and checked.
The old flow built with BUILD_PREVIEW=1, which is why lychee.toml:7 excludes pr-preview/pr-N/ URLs. That exclusion no longer matches anything this workflow produces.
The failure scenario is a PR that adds a new doc page, such as a new release-notes file or a new API page. Its canonical URL points at the production latest/ site, where the page doesn't exist until after merge and deploy. That is a 404, which retry_lychee.py correctly treats as permanent. Documentation links goes red, and once it is a required check the PR can't merge. The PR's own validation couldn't have caught this, because it adds no doc pages.

Possible fixes:

• Set CUDA_PYTHON_DOCS_DOMAIN to an excluded or local host (for example a file:// or .invalid domain) and exclude it in lychee.toml.
  Build with BUILD_PREVIEW=1 and a dummy PR_NUMBER, so the existing exclusion applies.
  Add an exclusion for ^https://nvidia\.github\.io/cuda-python/(latest|cuda-[a-z]+/latest)/.

====

Also from my agent, it seems like the cooldown, since it starts from scratch each time, is not going to be particularly effective.

timeout-minutes: 60 can cut off the "ten passes" guarantee for the rendered job. The job includes a docs build and up to 9 cooldowns, 60s then 120s each, which is about 17 minutes of sleeping. Every retry pass re-checks all local and file:// targets, since the PR notes that filesystem checks aren't cached. That is about 740k occurrences in the rendered tree, and the pass duration isn't stated. If a pass takes more than 4–5 minutes, a persistent 429 hits the timeout and the job is cancelled instead of reaching the clean "after 10 attempts" report. It still fails, but the summary is lost and the cause looks different. Either raise the timeout or document the observed pass duration.

====

Also from my agent. It called this "MEDIUM", but it seems pretty serious to me since it won't detect logical merge issues which are a large reason the lychee check exists.

Merge ref: Checking out pull_request.head.sha means the PR is checked without being merged into current main, unlike pre-commit.yml (default merge-ref checkout). I understand the reason: CUDA_PYTHON_DOCS_GITHUB_REF needs a SHA that exists upstream. It does mean that a main-side change, such as a page removed on main, isn't caught until after merge. This is probably acceptable, but a one-line comment would help.

[rwgk]

Converting to Draft mode before rebasing to fetch the latest updates from main. I don't want to trigger CI, only get a clean baseline for addressing @mdboom's feedback.

[rwgk]

/ok to test 081ded4

[rwgk]

@mdboom the CI is really slow today, but it looks like all jobs will be green eventually.

The below is mostly agent-generated (I switched up to codex GPT-6-Astra ultra), with small tweaks:

Replies to review: #2993 (review)

When CI monitoring stopped, full CI had 104 successful jobs and two A100 jobs queued, with no failures; its final status gate was still pending.

Canonical links for new documentation pages

You're right. Building the latest layout caused Sphinx to emit canonical URLs pointing at production, so a new page could fail with a 404 before it was published. The earlier successful CI runs didn't add a page and missed this case.

The original choice of BUILD_LATEST=1 was to assemble a consistent set of documentation trees for all four packages using the existing build scripts. We can retain that layout while checking the pages built for this revision: the source-build helper now sets CUDA_PYTHON_DOCS_DOMAIN to the absolute file:// URI of artifacts/docs. Canonical links resolve to the actual local output, so we check them rather than excluding them. This override is confined to the link-checking build; the wheel-based build and published canonical URLs keep their existing behavior.

Fixed in 456f145. A real build of all four documentation trees included two temporary new cuda-core pages with a link between them. All 1,118 canonical links resolved locally. With external network requests disabled, pinned Lychee passed both the new-page check and a complete local-file and anchor scan of the rendered tree. Removing the new target then correctly failed with a missing-file error. The committed regression tests also cover the helper's domain setup for paths with and without spaces. The actual PR documentation run additionally covered external links and passed both link jobs on their first checker attempt, with zero errors or timeouts.

Checking the PR merge revision

Agreed: the PR check should include its integration with the base branch. The original explicit head checkout was intended to give generated GitHub source links an ordinary commit SHA that GitHub could resolve. That precaution was unnecessary: we verified that GitHub source links at the test-merge SHA resolve and pass the pinned Lychee version.

The workflow now uses the default checkout revision, matching the standalone pre-commit workflow. For a PR event this is GitHub's test merge with the base branch; manual and nightly runs use their selected revision. Generated source links still use the actual checked-out SHA.

Fixed in 081ded4. A separate Git fixture reproduced the concern: the PR added a link while main removed its target, producing a clean merge. Pinned Lychee passed at the PR head and failed at the merge revision. In the actual PR run, both checkout logs confirm test-merge SHA 692e123, combining main at 4c893de with PR head 081ded4. All three jobs passed, including rendered documentation with source links at that merge SHA.

The nightly integration and cache reader also passed on their first workflow attempts. The reader restored both exact producer snapshots, passed both link checks, and skipped cache publication.

Full CI was triggered at PR head 081ded4 to cover the complete package build/test plan, the wheel-based documentation build and preview deployment, and the final status gate. The documentation build and preview deployment have both passed.

Retry count and the job timeout

The repeated passes reuse successful external-link results; only unsuccessful external checks and local files need checking again. We don't have enough representative cold-cache runs to estimate retry frequencies, and we have actually exhausted all ten attempts on a persistent HTTP 429, so the rationale shouldn't depend on that being extremely rare.

The two limits bounds are complementary safeguards: ten attempts limit repeated checking, while 60 minutes limits the total job duration.

Ten attempts means the initial check plus nine retries. The cooldowns total 17 minutes: one minute before the first retry, then two minutes before each of the remaining eight. That leaves 43 minutes for setup, building the documentation, and all ten checking passes.

Our measurements suggest substantial room within that budget. Building the documentation took about seven minutes, and a cold rendered check took about five minutes. Subsequent checks reuse successful external results: retries during an observed persistent HTTP 429 took roughly 40-60 seconds each.

Using those timings, even nine retries would give roughly 7 + 5 + 9 + 17 = 38 minutes, plus setup overhead. Consistent with that estimate, an actual job exhausted all ten attempts in about 37 minutes.

[coderabbitai]

📝 Summary

Summary by CodeRabbit

• New Features
  • Documentation links are now checked in pull requests, with separate checks for source documentation and freshly built pages.
  • Nightly checks can be run in documentation-links-only mode.
• Improvements
  • Temporary link-check failures are retried, and reports are available even when checks fail.
  • Windows pre-commit checks now support repositories with Git symlinks.
• Changes
  • The Windows pre-commit job has been removed from the main CI checks.

Walkthrough

The pull request adds authored and rendered documentation link checks, transient-failure retries, and nightly workflow integration. It also removes the Windows pre-commit job from the general CI workflow and enables Git symlinks in the standalone pre-commit workflow.

Changes

Documentation Link Checking

Layer / File(s)	Summary
Prepare documentation and link-check inputs ci/tools/build_docs_for_link_check.sh, ci/tools/prepare_lychee_inputs.py, cuda_core/pixi.toml, ci/tools/tests/test_build_docs_for_link_check.py, ci/tools/tests/test_prepare_lychee_inputs.py	The build script generates latest-only documentation in a local artifact directory. The input tool selects authored or rendered documentation files and writes absolute paths. Tests cover build settings and input selection.
Validate reports and retry transient failures ci/tools/retry_lychee.py, ci/tools/tests/test_retry_lychee.py	The retry helper validates Lychee reports, retries eligible transient failures up to the configured limit, and writes a Markdown summary. Tests cover report validation and retry outcomes.
Run pull-request and manual link checks .github/workflows/lychee.yml, .github/workflows/build-docs.yml, lychee.toml	The new workflow checks authored files and rendered HTML, manages caches and reports, and gates success on both checks. The prior rendered-link steps are removed from the documentation build workflow.
Integrate link checks into nightly runs .github/workflows/ci-nightly.yml	The nightly workflow adds a links-only dispatch mode, refreshes the link-check cache, and includes link-check results in full-run validation.

Pre-commit CI Updates

Layer / File(s)	Summary
Update pre-commit checks and contributor guidance .github/workflows/ci.yml, .github/workflows/pre-commit.yml, CONTRIBUTING.md	The general CI workflow removes the Windows pre-commit job and its aggregator requirement. The standalone workflow enables Git symlinks on Windows. Contributor guidance describes the pre-commit and documentation-link checks.

Assessment against linked issues

Objective	Addressed	Explanation
Required-check migration helper (#3002)	❌	This pull request adds the documentation link checker, not a required-check migration CLI. Issue #3002 identifies that helper as separate historical context.

Assessment against linked issues: Out-of-scope changes

Priority: ⬇️ Low

Change: Feature

Merge Risk: 🟡 Moderate · up to 081de

Windows pre-commit failures may no longer prevent merging. Restore the gate or require the replacement check before merging this change.

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to GitHub limitations.

⚠️ Outside diff range comments (1)

🟠 Major · important: Keep the Windows pre-commit gate until its replacement is required. · ci.yml:644

.github/workflows/ci.yml:644
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

important: Keep the Windows pre-commit gate until its replacement is required.

The Windows job can fail while Check job status and the required pre-commit.ci - pr check pass. The active main ruleset does not require Pre-commit (Windows), so that failure does not block merging when the other required checks pass. This conflicts with CONTRIBUTING.md’s instruction to resolve check failures before merging.

Restore the precommit-windows job and its aggregator check until the ruleset requires Pre-commit (Windows), or update the ruleset in the same rollout.

Source: Path instructions

---

ℹ️ Review info

⚙️ Run configuration

• Configuration used: Repository: NVIDIA/cuda-python/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 6a1eea8f-066c-4567-bbae-b6f1021ae3ae

📥 Commits

Reviewing files that changed from the base of the PR and between 4c893de and 081ded4.

📒 Files selected for processing (14)

• .github/workflows/build-docs.yml
• .github/workflows/ci-nightly.yml
• .github/workflows/ci.yml
• .github/workflows/lychee.yml
• .github/workflows/pre-commit.yml
• CONTRIBUTING.md
• ci/tools/build_docs_for_link_check.sh
• ci/tools/prepare_lychee_inputs.py
• ci/tools/retry_lychee.py
• ci/tools/tests/test_build_docs_for_link_check.py
• ci/tools/tests/test_prepare_lychee_inputs.py
• ci/tools/tests/test_retry_lychee.py
• cuda_core/pixi.toml
• lychee.toml

💤 Files with no reviewable changes (1)

• .github/workflows/build-docs.yml

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