Skip to content

Commit 911747a

Browse files
committed
Simplify Lychee source-link remapping
Signed-off-by: Ralf W. Grosse-Kunstleve <[email protected]>
1 parent a7d8e47 commit 911747a

12 files changed

Lines changed: 357 additions & 531 deletions

‎.github/actions/lychee-links/action.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,7 @@ runs:
6969
KIND: ${{ inputs.kind }}
7070
# Anything that can change a check result or the cache's meaning. The
7171
# hook configuration carries the native wheel pin and every hook option.
72-
POLICY_HASH: ${{ hashFiles('.pre-commit-config.yaml', 'lychee.toml', 'ci/tools/run_lychee.py', 'ci/tools/run_lychee_precommit.py', 'ci/tools/retry_lychee.py', 'ci/tools/checkout_link_defaults.py') }}
72+
POLICY_HASH: ${{ hashFiles('.pre-commit-config.yaml', 'lychee.toml', 'ci/tools/run_lychee.py', 'ci/tools/run_lychee_precommit.py', 'ci/tools/retry_lychee.py', 'ci/tools/checkout_source_links.py') }}
7373
run: |
7474
# Authored and rendered results stay apart: only rendered checks validate
7575
# fragments, and Lychee's cache does not record which validation ran.

‎.github/workflows/build-docs.yml‎

Lines changed: 1 addition & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -118,7 +118,7 @@ jobs:
118118
fi
119119
else
120120
FILE_HASH="${{ github.sha }}"
121-
DOCS_GITHUB_REF="${{ github.sha }}"
121+
DOCS_GITHUB_REF=$(python ci/tools/checkout_source_links.py --github-ref)
122122
fi
123123
124124
# make outputs from the previous job as env vars
@@ -295,19 +295,6 @@ jobs:
295295
with:
296296
python-version: "3.14"
297297

298-
- name: Discover repository link targets
299-
if: ${{ !inputs.is-release && startsWith(github.ref_name, 'pull-request/') }}
300-
# BEGIN SYNCED LYCHEE REPOSITORY METADATA
301-
env:
302-
LYCHEE_REPOSITORY: ${{ github.repository }}
303-
LYCHEE_DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
304-
run: >-
305-
python ci/tools/checkout_link_defaults.py
306-
--repository "$LYCHEE_REPOSITORY"
307-
--default-branch "$LYCHEE_DEFAULT_BRANCH"
308-
--github-env "$GITHUB_ENV"
309-
# END SYNCED LYCHEE REPOSITORY METADATA
310-
311298
- name: Check rendered documentation links through pre-commit
312299
if: ${{ !inputs.is-release && startsWith(github.ref_name, 'pull-request/') }}
313300
timeout-minutes: 60

‎.github/workflows/lychee.yml‎

Lines changed: 0 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -75,18 +75,6 @@ jobs:
7575
- name: Set pre-commit cache location
7676
run: echo "PRE_COMMIT_HOME=${RUNNER_TEMP}/pre-commit" >> "${GITHUB_ENV}"
7777

78-
- name: Discover repository link targets
79-
# BEGIN SYNCED LYCHEE REPOSITORY METADATA
80-
env:
81-
LYCHEE_REPOSITORY: ${{ github.repository }}
82-
LYCHEE_DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
83-
run: >-
84-
python ci/tools/checkout_link_defaults.py
85-
--repository "$LYCHEE_REPOSITORY"
86-
--default-branch "$LYCHEE_DEFAULT_BRANCH"
87-
--github-env "$GITHUB_ENV"
88-
# END SYNCED LYCHEE REPOSITORY METADATA
89-
9078
- name: Restore pre-commit environments
9179
uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
9280
with:

‎.github/workflows/pre-commit.yml‎

Lines changed: 0 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -70,18 +70,6 @@ jobs:
7070
- name: Set pre-commit cache location
7171
run: echo "PRE_COMMIT_HOME=${RUNNER_TEMP}/pre-commit" >> "${GITHUB_ENV}"
7272

73-
- name: Discover repository link targets
74-
# BEGIN SYNCED LYCHEE REPOSITORY METADATA
75-
env:
76-
LYCHEE_REPOSITORY: ${{ github.repository }}
77-
LYCHEE_DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
78-
run: >-
79-
python ci/tools/checkout_link_defaults.py
80-
--repository "$LYCHEE_REPOSITORY"
81-
--default-branch "$LYCHEE_DEFAULT_BRANCH"
82-
--github-env "$GITHUB_ENV"
83-
# END SYNCED LYCHEE REPOSITORY METADATA
84-
8573
- name: Restore pre-commit cache
8674
id: precommit-cache
8775
uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0

‎ci/README.md‎

Lines changed: 40 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -30,9 +30,9 @@ Two pre-commit hooks check links with one pinned native wheel (`lychee-bin`,
3030
see `.pre-commit-config.yaml`) through the wrapper `ci/tools/run_lychee.py`:
3131
`lychee` checks authored Markdown and reST (fragments unchecked), and the
3232
manual-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

3737
CI runs a hook through `ci/tools/run_lychee_precommit.py <authored|rendered>`,
3838
wrapped with the shared cache and report handling in
@@ -98,7 +98,7 @@ can stay unnoticed for up to 72 hours.
9898
The 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.
102102
Authored and rendered caches stay apart because only rendered checks validate
103103
fragments and Lychee's cache does not record which validation ran. URL results
104104
are shared across operating systems; pre-commit's installed environments keep
@@ -107,58 +107,49 @@ their OS- and Python-specific caches.
107107
### Repository Links
108108

109109
Documentation 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

‎ci/tools/build_docs_for_link_check.sh‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,10 @@ if [[ "${PIXI_ENVIRONMENT_NAME:-}" != "docs" ]]; then
1515
exit 1
1616
fi
1717

18-
export CUDA_PYTHON_DOCS_GITHUB_REF="${CUDA_PYTHON_DOCS_GITHUB_REF:-$(git rev-parse HEAD)}"
18+
if [[ -z "${CUDA_PYTHON_DOCS_GITHUB_REF:-}" ]]; then
19+
CUDA_PYTHON_DOCS_GITHUB_REF=$(python ci/tools/checkout_source_links.py --github-ref)
20+
fi
21+
export CUDA_PYTHON_DOCS_GITHUB_REF
1922
export BUILD_LATEST=1
2023
export BUILD_PREVIEW=0
2124

‎ci/tools/checkout_link_defaults.py‎

Lines changed: 0 additions & 194 deletions
This file was deleted.

0 commit comments

Comments
 (0)