← Back to issue list

Docs: Implement an alternative link checker

View original Github issue

Metadata

Project
starbase
Number
#417
Type
issue
State
open
Author
medubelko
Labels
Status: Triaged
Created
Updated
Closed
—

Current evaluation

Proposal to replace Sphinx's link checker with a faster alternative after it caused a 6-hour build hang on gnu.org. Triaged by maintainer but inactive for over a year; Sphinx linkcheck is still in use in the codebase.

Suggested action: keep open

Reason: The issue is labeled 'Status: Triaged' and the problem remains unresolved: docs/Makefile still invokes 'sphinx-build -b linkcheck' and docs/conf.py still sets 'linkcheck_retries = 20'. The 6-hour CI hang risk from external sites blocking requests is still present, so the issue is not irrelevant despite its age. No PR or follow-up has been filed to address it.

Impact: 45 Quick Win: 24.75 Staleness: 75 Complexity: 45 Confidence: 80 Support Request: 5

Issue body

In a recent [Rockcraft build](https://github.com/canonical/rockcraft/actions/runs/16355474142/job/46217812410?pr=921#step:6:5734), the sphinx-build link checker spent six hours trying to reach a link to [gnu.org](https://gnu.org). I've tried every timeout-related config setting available in the configuration, but none seem to stop it from infinitely looping. I think it's caused by the FSF's recent work walling themselves off from [DDoSing by LLM agents](https://www.fsf.org/blogs/sysadmin/our-small-team-vs-millions-of-bots). Something about the response causes it to keep trying, possibly because of a limitation with [`Retry-After`](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-linkcheck_rate_limit_timeout). Or, Sphinx's user agent might be blocked now. Or, FSF is sending bots into a maze. Regardless of what other domains are doing, it shouldn't bog our builds. If other savvy sites do likewise in the future, we don't want to be surprised by blocked builds. Sphinx's link checker has always been slow and its capabilities meagre. I'd like to pursue other link checking solutions.

Evaluation history

Date Model Scores Action Summary
qwen/qwen3.8-27b
Impact: 45
Quick Win: 24.75
Staleness: 75
Complexity: 45
Confidence: 80
Support Request: 5
keep open Proposal to replace Sphinx's link checker with a faster alternative after it caused a 6-hour build hang on gnu.org. Triaged by maintainer but inactive for over a year; Sphinx linkcheck is still in use in the codebase.
qwen/qwen3.6-35b-a3b
Staleness: 80
Complexity: 40
Confidence: 85
Support Request: 5
keep open Proposal to replace Sphinx's link checker with a faster alternative after it caused a 6-hour build hang on gnu.org. Currently triaged but inactive for a year.
qwen3.6-35b-a3b-mtp-q6
Staleness: 85
Complexity: 45
Confidence: 65
Support Request: 10
close stale Request to replace Sphinx's link checker due to infinite hangs on external domains. Triaged by a maintainer but inactive for over a year with only an automated Jira sync comment.
qwen3.6-35b-a3b-mtp-q6
Staleness: 75
Complexity: 40
Confidence: 70
Support Request: 5
keep open Replace Sphinx's link checker with a more reliable tool to prevent documentation builds from hanging on unresponsive domains. Status is triaged and awaiting assignment, with no recent activity.

Update history

No update history recorded yet.

Related work

  • Related To: starbase#444 (confidence 85%)

    Commit 9cbbaf5 'docs: make linkcheck more forgiving (#444)' added linkcheck_retries=20 and linkcheck_report_timeouts_as_broken=False as a partial mitigation, but did not replace the checker as this issue requests.

Related issues

No related issues found above the similarity threshold.