@@ -30,9 +30,9 @@ Two pre-commit hooks check links with one pinned native wheel (`lychee-bin`,
3030see ` .pre-commit-config.yaml ` ) through the wrapper ` ci/tools/run_lychee.py ` :
3131` lychee ` checks authored Markdown and reST (fragments unchecked), and the
3232manual-stage ` lychee-rendered ` checks the generated HTML in ` artifacts/docs ` ,
33- including fragments. Developers run the same hooks locally. Links to supported
34- repositories' default branches are checked against the proposed checkout, as
35- described under [ Repository Links] ( #repository-links ) .
33+ including fragments. Developers run the same hooks locally. Public repository
34+ ` main ` links are checked against the proposed checkout, as described under
35+ [ Repository Links] ( #repository-links ) .
3636
3737CI runs a hook through ` ci/tools/run_lychee_precommit.py <authored|rendered> ` ,
3838wrapped with the shared cache and report handling in
@@ -98,7 +98,7 @@ can stay unnoticed for up to 72 hours.
9898The action keys each baseline by checker kind and a hash of
9999` .pre-commit-config.yaml ` (hook options and wheel pin), ` lychee.toml ` , and
100100` ci/tools/run_lychee.py ` , ` run_lychee_precommit.py ` , ` retry_lychee.py ` , and
101- ` checkout_link_defaults .py` , so editing any of them starts a cold cache.
101+ ` checkout_source_links .py` , so editing any of them starts a cold cache.
102102Authored and rendered caches stay apart because only rendered checks validate
103103fragments and Lychee's cache does not record which validation ran. URL results
104104are shared across operating systems; pre-commit's installed environments keep
@@ -107,58 +107,49 @@ their OS- and Python-specific caches.
107107### Repository Links
108108
109109Documentation can link to a path added or moved in the same PR using its
110- intended default-branch URL. For example, a URL ending in
111- ` tree/<default-branch>/new-directory ` is validated before that directory
112- exists on the remote default branch. Lychee remaps the
113- validation target; source files and published documentation keep their URLs.
114-
115- ` ci/tools/checkout_link_defaults.py ` discovers each source repository's default
116- branch, rather than assuming it is named ` main ` . It supports the canonical
117- public repository and the repository being checked. A synchronized repository
118- with a different default branch, such as ` ctk-next ` , can retain public source
119- links and also use its own repository links. Each source URL is matched against
120- the default branch of the repository named in that URL.
110+ intended public URL, for example
111+ ` https://github.com/NVIDIA/cuda-python/tree/main/new-directory ` . Lychee
112+ validates the proposed target before it exists on public ` main ` . Only the
113+ validation target changes; source files and built documentation retain their URLs.
121114
122- - Authored Markdown and reST map to file URIs in the working tree, including
123- uncommitted and unpushed paths. Missing files and directories fail even if a
124- prior check succeeded. Authored checks continue to omit fragment validation.
125- - Rendered HTML maps to GitHub's file or directory view at the actual
126- checked-out commit in the current repository, preserving fragment checks.
127- - Only complete URL prefixes naming a supported repository and its default
128- branch are remapped. Tags, explicit commits, other branches, unrelated
129- repositories, and URLs embedded inside other URLs retain their targets.
130-
131- CI takes the current repository and default branch from the workflow event.
132- When running in another repository, a preparation step also queries the public
133- repository's advertised default branch once. Hook invocations use the prepared
134- metadata without further discovery requests. The PR base branch and current
135- working branch do not determine which source URLs are remapped.
136-
137- Local hooks use cached remote ` HEAD ` references and make no discovery requests.
138- The ` upstream ` remote identifies the checkout's repository when present;
139- otherwise ` origin ` does. To select it explicitly, including when using other
140- remote names:
115+ ` ci/tools/checkout_source_links.py ` matches the complete public repository
116+ prefix followed by ` blob/main/ ` or ` tree/main/ ` :
141117
142- ``` bash
143- git config lychee.repository OWNER/REPOSITORY
144- ```
145-
146- The helper matches remote URLs to find each selected repository's metadata.
147- If a cached default is missing or conflicting, it reports the remote to
148- refresh, for example:
118+ - Authored Markdown and reST map to file URIs in the working tree, including
119+ uncommitted and unpushed paths. Missing files and directories fail even after
120+ an earlier success. These checks need no repository metadata and retain the
121+ existing policy of omitting fragments.
122+ - Rendered HTML from the public repository maps source links to GitHub's file
123+ or directory view at the actual checked-out commit, retaining fragment checks.
124+ That commit must be available on GitHub.
125+ - Rendered HTML from other repositories maps the same public source links to
126+ local files and directories. Only those source links omit fragments, since
127+ local files do not reproduce every GitHub source-view anchor. Generated
128+ documentation pages and their anchors still receive full validation.
129+
130+ Tags, explicit commits, other branches, unrelated repositories, and URLs embedded
131+ inside other URLs retain their original targets. There is no default-branch
132+ lookup or remote ` HEAD ` requirement. A future change to the public URL convention
133+ would require an explicit update to these matching rules.
134+
135+ For rendered checks and checking builds, CI supplies the checkout identity
136+ through ` GITHUB_REPOSITORY ` . Local runs use ` git config lychee.repository ` , or
137+ otherwise the ` upstream ` remote followed by ` origin ` . A checkout whose remotes
138+ only name a fork can select public-repository validation explicitly:
149139
150140``` bash
151- git remote set-head upstream --auto
141+ git config lychee.repository NVIDIA/cuda-python
152142```
153143
154- A synchronized checkout also needs a remote for the public repository, with
155- its default cached in the same way, for example `git remote set-head public_repo
156- --auto`. Fetch the default branch first if Git requests it. Refresh these
157- references after a repository changes its default branch.
144+ The checking build uses the public checkout's actual commit for generated
145+ example links. In other repositories it uses ` main ` , allowing those public URLs
146+ to receive the same local target checks without inserting another repository's
147+ commit into public links. An explicit ` CUDA_PYTHON_DOCS_GITHUB_REF ` override is
148+ retained; release builds continue to use their release tags.
158149
159- These rules validate the proposed default-branch tree. Before adopting them on
160- a maintenance branch, choose an explicit policy for links that intentionally
161- point to a different tree from the maintenance checkout.
150+ These rules validate the proposed source tree. Before adopting them on a
151+ maintenance branch, choose an explicit policy for links that intentionally point
152+ to a different tree from the maintenance checkout.
162153
163154## Temporary Pixi Lockfile Maintenance Pause
164155
0 commit comments