Skip to content

Commit 1d7b804

Browse files
juenglinrwgk
authored andcommitted
ci: trim the Lychee link-check implementation
Reduce the code behind the pre-commit-based link checks without changing which checks run, how they fail, or how results are cached and retried. - Replace ci/tools/lychee_cache.py and its tests with a small composite action, .github/actions/lychee-links. It hashes the policy files with hashFiles(), restores and publishes the URL cache, runs the driver, and uploads reports, so the pre-commit, nightly, and docs-build workflows each make one call instead of repeating five to eight steps. - Drop LYCHEE_CACHE_DIR. The rendered hook always uses the gitignored .lychee-rendered directory. - Make nightly the only producer of the shared baselines. Linux pre-commit runs on the default branch no longer publish the authored cache. - Remove retry branches for native exit codes other than 0 and 2. The driver raises on those before retrying, so they could not run. - Fold the two helpers still in use from prepare_lychee_inputs.py into run_lychee.py and delete the module, whose authored-file selection has been done by the hook configuration since the Lychee action was removed. - Trim tests that duplicated each other or exercised removed paths, and shorten the README section. Signed-off-by: Ralf Juengling <[email protected]> Signed-off-by: Ralf W. Grosse-Kunstleve <[email protected]>
1 parent 7625aad commit 1d7b804

14 files changed

Lines changed: 229 additions & 637 deletions
Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2+
#
3+
# SPDX-License-Identifier: Apache-2.0
4+
5+
name: Check documentation links
6+
description: Run a configured Lychee pre-commit hook with the shared URL cache and retained reports
7+
8+
inputs:
9+
kind:
10+
description: "Which hook to run: authored or rendered"
11+
required: true
12+
policy:
13+
description: "check accepts up to 10 rate-limited URLs; cache-warm reports every unresolved link as a warning"
14+
default: check
15+
refresh:
16+
description: "Check links afresh and publish the successful results as the new baseline"
17+
default: "false"
18+
19+
# Callers provide Python and the checked-out repository; the build of any
20+
# rendered documentation must already be complete.
21+
runs:
22+
using: composite
23+
steps:
24+
- name: Describe the link cache
25+
id: cache
26+
shell: bash --noprofile --norc -euo pipefail {0}
27+
env:
28+
KIND: ${{ inputs.kind }}
29+
# Anything that can change a check result or the cache's meaning. The
30+
# hook configuration carries the native wheel pin and every hook option.
31+
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') }}
32+
run: |
33+
# Authored and rendered results stay apart: only rendered checks validate
34+
# fragments, and Lychee's cache does not record which validation ran.
35+
case "${KIND}" in
36+
authored) path=.lycheecache ;;
37+
rendered) path=.lychee-rendered/.lycheecache ;;
38+
*) echo "::error::Unknown link-check kind: ${KIND}"; exit 1 ;;
39+
esac
40+
prefix="lychee-v1-${KIND}-${POLICY_HASH}-baseline-"
41+
echo "path=${path}" >> "${GITHUB_OUTPUT}"
42+
echo "prefix=${prefix}" >> "${GITHUB_OUTPUT}"
43+
echo "key=${prefix}${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}" >> "${GITHUB_OUTPUT}"
44+
45+
- name: Restore successful link checks
46+
# Refresh mode deliberately skips earlier URL results.
47+
if: ${{ inputs.refresh != 'true' }}
48+
uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
49+
with:
50+
path: ${{ steps.cache.outputs.path }}
51+
key: ${{ steps.cache.outputs.key }}
52+
restore-keys: ${{ steps.cache.outputs.prefix }}
53+
enableCrossOsArchive: true
54+
55+
- name: Check links through the configured pre-commit hook
56+
shell: bash --noprofile --norc -euo pipefail {0}
57+
env:
58+
KIND: ${{ inputs.kind }}
59+
POLICY: ${{ inputs.policy }}
60+
GITHUB_TOKEN: ${{ github.token }}
61+
run: |
62+
# Install into the interpreter that runs the driver, whatever shell
63+
# profile the caller's other steps use.
64+
python -m pip install pre-commit
65+
python ci/tools/run_lychee_precommit.py "${KIND}" --policy "${POLICY}" --max-attempts 3 \
66+
--report "${RUNNER_TEMP}/lychee-reports/lychee-${KIND}.json"
67+
68+
- name: Publish fresh successful link checks
69+
# Only nightly refreshes publish, so every pull request restores the same
70+
# baseline. Saving keeps original timestamps and never caches failures.
71+
if: ${{ !cancelled() && inputs.refresh == 'true' }}
72+
uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
73+
with:
74+
path: ${{ steps.cache.outputs.path }}
75+
key: ${{ steps.cache.outputs.key }}
76+
enableCrossOsArchive: true
77+
78+
- name: Upload link-check reports
79+
if: ${{ always() }}
80+
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
81+
with:
82+
name: lychee-${{ inputs.kind }}-${{ runner.os }}-${{ github.run_id }}-${{ github.run_attempt }}
83+
path: ${{ runner.temp }}/lychee-reports/
84+
if-no-files-found: ignore
85+
retention-days: 7

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

Lines changed: 7 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -287,45 +287,20 @@ jobs:
287287
# Check links and anchors in the rendered HTML built above.
288288
# Links in authored Markdown and reST files are checked separately by the
289289
# ordinary Linux/Windows pre-commit jobs.
290-
- name: Install pre-commit for rendered link checks
290+
# The link-check action runs in a non-login shell, so give it a known
291+
# interpreter instead of the conda environment used above.
292+
- name: Set up Python for link checks
291293
if: ${{ !inputs.is-release && startsWith(github.ref_name, 'pull-request/') }}
292-
run: |
293-
echo "PRE_COMMIT_HOME=${RUNNER_TEMP}/pre-commit" >> "${GITHUB_ENV}"
294-
echo "LYCHEE_CACHE_DIR=${RUNNER_TEMP}/lychee-rendered" >> "${GITHUB_ENV}"
295-
python -m pip install pre-commit
296-
297-
- name: Describe the rendered link cache
298-
if: ${{ !inputs.is-release && startsWith(github.ref_name, 'pull-request/') }}
299-
id: lychee-cache
300-
run: python ci/tools/lychee_cache.py rendered --github-output "${GITHUB_OUTPUT}"
301-
302-
- name: Restore successful rendered link checks
303-
if: ${{ !inputs.is-release && startsWith(github.ref_name, 'pull-request/') }}
304-
uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
294+
uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
305295
with:
306-
path: ${{ steps.lychee-cache.outputs.path }}
307-
key: ${{ steps.lychee-cache.outputs.key }}
308-
restore-keys: ${{ steps.lychee-cache.outputs.prefix }}
309-
enableCrossOsArchive: true
296+
python-version: "3.14"
310297

311298
- name: Check rendered documentation links through pre-commit
312299
if: ${{ !inputs.is-release && startsWith(github.ref_name, 'pull-request/') }}
313300
timeout-minutes: 60
314-
env:
315-
GITHUB_TOKEN: ${{ github.token }}
316-
run: >-
317-
python ci/tools/run_lychee_precommit.py rendered
318-
--policy check --max-attempts 3
319-
--report "${RUNNER_TEMP}/lychee-reports/lychee-rendered.json"
320-
321-
- name: Upload rendered link-check reports
322-
if: ${{ always() && !inputs.is-release && startsWith(github.ref_name, 'pull-request/') }}
323-
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
301+
uses: ./.github/actions/lychee-links
324302
with:
325-
name: lychee-rendered-${{ github.run_id }}-${{ github.run_attempt }}
326-
path: ${{ runner.temp }}/lychee-reports/
327-
if-no-files-found: ignore
328-
retention-days: 7
303+
kind: rendered
329304

330305
- name: Upload docs GitHub Pages artifact
331306
if: ${{ inputs.deploy-docs }}

‎.github/workflows/lychee.yml‎

Lines changed: 8 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,8 @@
44

55
# Warm authored and rendered link caches through the configured pre-commit
66
# hooks. Ordinary PRs reuse authored results; full docs CI reuses rendered
7-
# results. Nightly starts afresh and reports unresolved links as warnings.
7+
# results. Nightly starts afresh, reports unresolved links as warnings, and is
8+
# the only producer of both shared baselines.
89

910
name: "CI: Documentation links"
1011

@@ -71,10 +72,8 @@ jobs:
7172
with:
7273
python-version: ${{ env.PYTHON_VERSION }}
7374

74-
- name: Set link-check cache locations
75-
run: |
76-
echo "PRE_COMMIT_HOME=${RUNNER_TEMP}/pre-commit" >> "${GITHUB_ENV}"
77-
echo "LYCHEE_CACHE_DIR=${RUNNER_TEMP}/lychee-rendered" >> "${GITHUB_ENV}"
75+
- name: Set pre-commit cache location
76+
run: echo "PRE_COMMIT_HOME=${RUNNER_TEMP}/pre-commit" >> "${GITHUB_ENV}"
7877

7978
- name: Restore pre-commit environments
8079
uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
@@ -83,9 +82,6 @@ jobs:
8382
key: pre-commit-${{ runner.os }}-py${{ steps.python.outputs.python-version }}-${{ hashFiles('.pre-commit-config.yaml') }}
8483
restore-keys: pre-commit-${{ runner.os }}-py${{ env.PYTHON_VERSION }}
8584

86-
- name: Install pre-commit
87-
run: python -m pip install pre-commit
88-
8985
- name: Setup pixi
9086
if: ${{ matrix.kind == 'rendered' }}
9187
uses: ./.github/actions/setup-pixi
@@ -94,42 +90,9 @@ jobs:
9490
if: ${{ matrix.kind == 'rendered' }}
9591
run: pixi run --manifest-path cuda_core/pixi.toml -e docs docs-build-all-latest
9692

97-
- name: Describe the link cache
98-
id: lychee-cache
99-
run: python ci/tools/lychee_cache.py "${{ matrix.kind }}" --github-output "${GITHUB_OUTPUT}"
100-
101-
- name: Restore successful link checks
102-
# Refresh mode deliberately skips yesterday's URL results.
103-
if: ${{ !inputs.refresh-cache }}
104-
uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
105-
with:
106-
path: ${{ steps.lychee-cache.outputs.path }}
107-
key: ${{ steps.lychee-cache.outputs.key }}
108-
restore-keys: ${{ steps.lychee-cache.outputs.prefix }}
109-
enableCrossOsArchive: true
110-
11193
- name: Check documentation links through pre-commit
112-
env:
113-
GITHUB_TOKEN: ${{ github.token }}
114-
run: >-
115-
python ci/tools/run_lychee_precommit.py "${{ matrix.kind }}"
116-
--policy "${{ inputs.refresh-cache && 'cache-warm' || 'check' }}"
117-
--max-attempts 3
118-
--report "${RUNNER_TEMP}/lychee-reports/lychee-${{ matrix.kind }}.json"
119-
120-
- name: Publish fresh successful link checks
121-
if: ${{ !cancelled() && inputs.refresh-cache && steps.lychee-cache.outputs.key != '' }}
122-
uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
123-
with:
124-
path: ${{ steps.lychee-cache.outputs.path }}
125-
key: ${{ steps.lychee-cache.outputs.key }}
126-
enableCrossOsArchive: true
127-
128-
- name: Upload link-check reports
129-
if: ${{ always() }}
130-
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
94+
uses: ./.github/actions/lychee-links
13195
with:
132-
name: lychee-${{ matrix.kind }}-${{ github.run_id }}-${{ github.run_attempt }}
133-
path: ${{ runner.temp }}/lychee-reports/
134-
if-no-files-found: ignore
135-
retention-days: 7
96+
kind: ${{ matrix.kind }}
97+
policy: ${{ inputs.refresh-cache && 'cache-warm' || 'check' }}
98+
refresh: ${{ inputs.refresh-cache || false }}

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

Lines changed: 9 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ on:
1010
push:
1111
# PR events cover draft and fork PRs without also checking copy-pr-bot's
1212
# pull-request/N mirrors. Only the default branch needs a push check, and
13-
# it is the only ref that refreshes the saved cache (see the save step).
13+
# it is the only ref that saves the pre-commit environment cache.
1414
branches:
1515
- "main"
1616
- "ctk-next"
@@ -139,53 +139,21 @@ jobs:
139139
LYCHEE_SMOKE_DIR: ${{ steps.lychee-smoke.outputs.directory }}
140140
run: python ci/tools/smoke_test_lychee_precommit.py --cleanup "$LYCHEE_SMOKE_DIR"
141141

142-
- name: Describe the authored link cache
143-
id: lychee-cache
144-
run: python ci/tools/lychee_cache.py authored --github-output "${GITHUB_OUTPUT}"
145-
146-
- name: Restore successful link checks from the shared baseline
147-
uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
142+
# Warm only Lychee from the shared nightly baseline, retaining successful
143+
# checks between up to three attempts. The full suite below runs once:
144+
# formatter changes must remain failures. A missing baseline is supported;
145+
# the first pass then checks afresh.
146+
- name: Warm the Lychee cache
147+
uses: ./.github/actions/lychee-links
148148
with:
149-
path: ${{ steps.lychee-cache.outputs.path }}
150-
key: ${{ steps.lychee-cache.outputs.key }}
151-
restore-keys: ${{ steps.lychee-cache.outputs.prefix }}
152-
enableCrossOsArchive: true
153-
154-
# Warm only Lychee, retaining successful checks between attempts. The
155-
# full suite below runs once: formatter changes must remain failures.
156-
# A missing baseline is supported; the first pass then checks afresh.
157-
- name: Warm the Lychee cache with up to three hook attempts
158-
env:
159-
GITHUB_TOKEN: ${{ github.token }}
160-
run: >-
161-
python ci/tools/run_lychee_precommit.py authored
162-
--policy cache-warm --max-attempts 3
163-
--report "${RUNNER_TEMP}/lychee-reports/lychee-authored.json"
149+
kind: authored
150+
policy: cache-warm
164151

165152
- name: Run pre-commit
166153
env:
167154
GITHUB_TOKEN: ${{ github.token }}
168155
run: pre-commit run --all-files --show-diff-on-failure
169156

170-
- name: Save successful authored link checks from main
171-
# Nightly and Linux runs on the default branch supply the shared baseline.
172-
# PR runs only restore it; saving preserves timestamps and never caches failures.
173-
if: ${{ !cancelled() && runner.os == 'Linux' && github.ref_name == github.event.repository.default_branch && steps.lychee-cache.outputs.key != '' }}
174-
uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
175-
with:
176-
path: ${{ steps.lychee-cache.outputs.path }}
177-
key: ${{ steps.lychee-cache.outputs.key }}
178-
enableCrossOsArchive: true
179-
180-
- name: Upload Lychee warm-up reports
181-
if: ${{ always() }}
182-
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
183-
with:
184-
name: lychee-precommit-${{ runner.os }}-${{ github.run_id }}-${{ github.run_attempt }}
185-
path: ${{ runner.temp }}/lychee-reports/
186-
if-no-files-found: ignore
187-
retention-days: 7
188-
189157
- name: Save pre-commit cache
190158
# Only the default branch saves, so per-PR merge refs don't store their
191159
# own duplicate copies. !cancelled() keeps a push that fails lint from

0 commit comments

Comments
 (0)