Skip to content

fix: update the link check config in conf.py and linkcheck.yml - #1196

Merged
TimMonko merged 7 commits into
napari:mainfrom
lundybernard:linkcheck-config
Nov 5, 2026
Merged

TimMonko merged 7 commits into
napari:mainfrom
lundybernard:linkcheck-config

Conversation

@lundybernard

@lundybernard lundybernard commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

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

Description

Resolves: #1190

  • Set myst_linkify_fuzzy_links = False. Bare file names such as conf.py no longer become http://conf.py links. Seventeen site names that relied on fuzzy linkify get explicit links.
  • Extend linkcheck_anchors_ignore with the GitHub anchors that JavaScript adds: single-line #L, #readme, and #issue-.
  • Ignore the hosts that answer the checker with 403 or 429, and the hosts that refuse connections from CI. The www.slicer.org entry 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.
  • Cut release previews at a space in update_release_docs.py. A cut inside a Markdown link produced the broken https://github.com/napari/napari/p link.
  • Ignore four dead links whose sources live in the napari examples and the npe2 docs templates. Drop this commit once docs: update moved tutorial links in two examples napari#9810 and docs: fix dead links in the plugin guide templates and WidgetContribution npe2#528 land and the docs constraints pin an npe2 release that carries them.
  • Write a fallback report in linkcheck.yml when the build fails before the link check runs. The issue step then files or updates the report on every failure path.
  • The link check on this branch fails only on what the links PR fixes: 19 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

@github-actions github-actions Bot added documentation Improvements or additions to documentation maintenance CI, dependencies, and other maintenance labels Oct 29, 2026
@github-actions

github-actions Bot commented Oct 29, 2026 •

Copy link
Copy Markdown

@lundybernard

Copy link
Copy Markdown
Contributor Author

@napari-bot make slimfast

docs build failed due to a timeout.

@lundybernard

Copy link
Copy Markdown
Contributor Author

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.

@TimMonko

TimMonko commented Nov 2, 2026

Copy link
Copy Markdown
Member

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.

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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds good to me!

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] + '...'

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

oh thank you! a lovely change :)

Comment thread docs/conf.py
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 = [

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can you explain this more to me? it's that URLs with things like issuecomment aren't somehow the real link?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Its a bit complicated. The root problem is github's lazy-loading, and how the link-check handles it.


Technical walkthrough:

  1. 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 #.
  2. Sphinx linkcheck requests the URL. A 200 proves the page exists.
  3. 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.
  4. 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.
  5. 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.
  1. 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.

@lundybernard lundybernard Nov 3, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The REVIEW FIX commit shows the updated text in isolation

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you! Looks good

@lundybernard

Copy link
Copy Markdown
Contributor Author

Confirmed, the cert is fixed now: Let's Encrypt, verifies clean, https
returns 200. Nothing to change here.

@lundybernard
lundybernard force-pushed the linkcheck-config branch 3 times, most recently from d0c3f38 to 36bd7d9 Compare November 3, 2026 19:13
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]
@TimMonko TimMonko added this to the 0.11.0 milestone Nov 4, 2026
@TimMonko

TimMonko commented Nov 4, 2026

Copy link
Copy Markdown
Member

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.

@lundybernard

Copy link
Copy Markdown
Contributor Author

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

TimMonko pushed a commit that referenced this pull request Nov 5, 2026
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.
@TimMonko

TimMonko commented Nov 5, 2026

Copy link
Copy Markdown
Member

Thank you for the explanation on your process, it definitely helped me approach re-reviewing these better. 🍻

@TimMonko
TimMonko merged commit a5a5310 into napari:main Nov 5, 2026
10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation maintenance CI, dependencies, and other maintenance

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Link Checker Report

2 participants