Skip to content

docs: ignore doi.org in linkcheck, treat timeouts as non-broken#423

Merged
rkingsbury merged 1 commit into
mainfrom
fix/linkcheck-doi-timeouts
Jun 15, 2026
Merged

docs: ignore doi.org in linkcheck, treat timeouts as non-broken#423
rkingsbury merged 1 commit into
mainfrom
fix/linkcheck-doi-timeouts

Conversation

@rkingsbury

Copy link
Copy Markdown
Member

Summary

The links tox environment runs sphinx-build -W -b linkcheck, which treats all warnings as errors. Two categories of spurious failures were identified:

  1. 403 errors from DOI redirectsdoi.org links redirect to publisher sites (Elsevier, Wiley, ACS, etc.) that block CI runners with 403 responses. The links themselves are valid; the publishers just reject automated requests.
  2. Transient timeouts — intermittent network timeouts in CI emit a warning that -W converts to a build error, causing flaky failures unrelated to the actual content.

Changes to docs/conf.py

  • Added r"https://doi\.org/.*" to linkcheck_ignore so DOI links are skipped entirely during link checking
  • Set linkcheck_report_timeouts_as_broken = False so timeout events are reported as timeout status (not broken), which does not emit a warning and therefore does not trigger -W
  • Set linkcheck_retries = 3 to give flaky links a few chances before reporting failure

Additional domains (e.g. ACS, Wiley, Elsevier) can be appended to linkcheck_ignore as they are identified.

This PR was authored by OpenAI Claude

@rkingsbury rkingsbury added docs documentation github_actions Pull requests that update GitHub Actions code labels Jun 15, 2026
@rkingsbury

Copy link
Copy Markdown
Member Author

Fixes #357

@rkingsbury rkingsbury added this to the v1.5.0 milestone Jun 15, 2026
@rkingsbury rkingsbury merged commit 8353014 into main Jun 15, 2026
1 check passed
@rkingsbury rkingsbury deleted the fix/linkcheck-doi-timeouts branch June 15, 2026 21:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs documentation github_actions Pull requests that update GitHub Actions code

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant