Repository navigation
fix: update the link check config in conf.py and linkcheck.yml - #1196
Conversation
|
@napari-bot make slimfast docs build failed due to a timeout. |
|
Minor issue beyond our control: http://www.cellimagelibrary.org/ redirects to https but has a cert issue, so it fails the link-check and when a user opens it in a browser, should be fine when the site fixes its cert. |
eff4c86 to
2861e34
Compare
I suspect this cert issue is fixed now based on my checking earlier -- never know how CI handles things |
| linux-teardown: "echo 'skip teardown'" | ||
|
|
||
| - name: Write a fallback report | ||
| # a build that fails before the link checker runs writes no report |
There was a problem hiding this comment.
Can you describe in more detail why this fallback exists? Is this because we need the build to succeed for the linkcheck to happen? I guess I don't know why it needs to make a fallback
There was a problem hiding this comment.
The fallback is optional, but I think its a good idea.
Anything that causes the sphinx build to fail will prevent the link checker from running, and the job then fails with nothing but a red job run, which has proven to be easy to ignore. With the fallback we get an issue.
One concern is that the issues will be noisy, but it should stick to updating a single issue instead of creating duplicates. So i would add it and we can always remove it if it proves not to be useful.
| if len(preview) > 150: | ||
| preview = preview[:150] + '...' | ||
| # Cut at a space, so that the cut never splits a URL. | ||
| preview = preview[:150].rsplit(' ', 1)[0] + '...' |
There was a problem hiding this comment.
oh thank you! a lovely change :)
| linkcheck_anchors_ignore = [r'^!', r'L\d+-L\d+', r'r\d+', r'issuecomment-\d+'] | ||
| # GitHub adds line, comment, readme, and issue anchors with JavaScript. | ||
| # The fetched HTML does not contain them. | ||
| linkcheck_anchors_ignore = [ |
There was a problem hiding this comment.
can you explain this more to me? it's that URLs with things like issuecomment aren't somehow the real link?
There was a problem hiding this comment.
Its a bit complicated. The root problem is github's lazy-loading, and how the link-check handles it.
Technical walkthrough:
- A link like Installing some plugins fails when conda-based environments are mixed with builtin pip installer napari#3223 (comment)
has two parts: the URL and the fragment after #. - Sphinx linkcheck requests the URL. A 200 proves the page exists.
- Because the link has a fragment, Sphinx also parses the HTML it received
and searches for an element with id="issuecomment-972189348" or the same name. - If no element matches, Sphinx reports the link as broken with the text
"Anchor 'issuecomment-972189348' not found". The page was fine. The report
lists it as a failure anyway. - GitHub does not put every id into the HTML it sends.
- File views draw the line numbers in the browser, so #L49 is missing.
- Repo pages draw the README section in the browser, so #readme is missing.
- Long issue threads ship only the first batch of comments,
and the rest load when scrolling,
so a comment deep in a 30-comment thread is missing.
- linkcheck_anchors_ignore is a list of regexes matched against the fragment.
On a match, Sphinx skips step 3 and keeps step 2. The URL is still checked.
The alternative is linkcheck_anchors = False, which skips step 3 for every
site. I prefer the list, because anchor checks on napari.org and other docs
sites can catch real breaks when a heading is renamed.
I'll update that comment to make it more clear.
There was a problem hiding this comment.
The REVIEW FIX commit shows the updated text in isolation
|
Confirmed, the cert is fixed now: Let's Encrypt, verifies clean, https |
d0c3f38 to
36bd7d9
Compare
The link checker reports each fuzzy link to a bare file name, such as http://conf.py, as broken. Bare site names in narrative pages, such as napari.org, get explicit links and stay links. Site names in release-note PR titles become plain text. Refs: napari#1190 Assisted-by: claude-code:claude-opus-5-5 [The Engineer]
rewrite_github_anchor leaves line, readme, and issue anchors unchanged and relies on this list to skip them. The list matched line ranges only, so single-line, readme, and issue anchors failed the check. Refs: napari#1190 Assisted-by: claude-code:claude-opus-5-5 [The Engineer] Assisted-by: claude-code:claude-sonnet-5-5 [The Mechanic]
Each entry fails in every CI run, but the page is live: it loads in a default client, or its own site links it as current. These failures are blocks against automated clients, not dead links. Refs: napari#1190 Assisted-by: claude-code:claude-opus-5-5 [The Engineer]
generate_release_list cut each preview at 150 characters. A cut inside a Markdown link left a partial URL, which linkify turned into a broken link such as https://github.com/napari/napari/p in release/index.md. Refs: napari#1190 Assisted-by: claude-code:claude-opus-5-5 [The Engineer]
The gallery pages come from the napari examples. The plugin guides and the contributions reference come from npe2 templates. A change in this repository cannot reach these links. Resolves: napari#1190 Assisted-by: claude-code:claude-opus-5-5 [The Engineer]
create-issue-from-file logs a missing output.txt as not found and passes, so a build that fails early files no report. The fallback body states the failure and links the run. Assisted-by: claude-code:claude-opus-5-5 [The Engineer]
36bd7d9 to
3de2d6a
Compare
|
Hi @lundybernard is this ready now? I think, for me, the repeated force-pushing is not something we are used to, so it's hard to know if you are 'finalizing' the PR or trying to trigger CI or whatnot. In our project, we are totally ok with messy commit histories, since we use squash and merge, so when we see the recent PRs we know what people are addressing. You are ok to continue committing as you are, it's just not what I am familiar with and could use assistant in knowing how to approach review. |
|
@TimMonko It is ready to merge. I usually craft PR history fairly carefully to make review easier, and on my projects I do merge commits to preserve that history. During the review process I'll add temporary '[REVIEW FIX]' commits to address specific changes, then do a fixup rebase to fold those changes in. If you want to squash merge then there's no reason to do the final fixup. Most of the force-push work to rebase the branch instead of merging changes into it. Occasionally its to cleanup a long list of REVIEW FIX commits, if I've had to make a lot of changes during review, for readability. |
Automated cleanup of broken links. worth considering, this removes dead-links which my agent could not find a suitable new target for, we could consider them on a case-by-case basis, I don't think there's any value in keeping the dead links especially since they are preserved in history if anyone needs to dig them up. --- :robot: _AI text below_ :robot: # References and relevant issues - Fixes the moved, dead, and `src/` layout part of the broken links reported in #1190 - Follows the discussion in #1179; full analysis at 3M1LY-lb#2 - Covers the 13 dead testing guide links in #1174 - Merges before #1196 which updates the link check config in `conf.py` and `linkcheck.yml` # Description Resolves: #1174 - Point 20 links at napari `main` to the `src/` layout, and the graph node links that `update_ui_sections_docs.py` builds. Links pinned to a commit or a tag keep their old paths. - Update or unlink 30 moved and dead external links. Links without a replacement keep their text. - The link check on this branch fails only on what the config PR fixes: 28 linkify false positives (`http://conf.py` shapes), 22 GitHub anchor misses, 18 bot-blocked hosts, 7 lines for the four links that napari and npe2 sources own, and 1 cut release preview. Run: https://github.com/3M1LY-lb/docs/actions/runs/40582738610 - The deployment guide PR rewrites the `docs_deployment.md` bullet where this PR unlinks `unversioned_pages.yml`. Keep that PR's version of the bullet when the two meet.
|
Thank you for the explanation on your process, it definitely helped me approach re-reviewing these better. 🍻 |
Many fixes for the link-check configuration to resolve failing/flakey checks, and turn the checker green. Includes a lot of ignored hosts that have proven to be unreliable for various reasons.
🤖 AI text below 🤖
References and relevant issues
src/layout linksDescription
Resolves: #1190
myst_linkify_fuzzy_links = False. Bare file names such asconf.pyno longer becomehttp://conf.pylinks. Seventeen site names that relied on fuzzy linkify get explicit links.linkcheck_anchors_ignorewith the GitHub anchors that JavaScript adds: single-line#L,#readme, and#issue-.www.slicer.orgentry looks like an outage, not a block. The host has refused all connections since 2026-10-27 02:00 UTC. Drop that entry if the site is back.update_release_docs.py. A cut inside a Markdown link produced the brokenhttps://github.com/napari/napari/plink.linkcheck.ymlwhen the build fails before the link check runs. The issue step then files or updates the report on every failure path.src/layout 404s and 30 moved or dead links. Run: https://github.com/3M1LY-lb/docs/actions/runs/40582741894. Both PRs together give a tree whose link check passes: https://github.com/3M1LY-lb/docs/actions/runs/40557580318