sphinx-doc / sphinx-doc/sphinx
Option to ignore `linkcheck` for SSL error
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
Is your feature request related to a problem? Please describe.
Whenever a website causes SSL error because their certificate expired, linkcheck causes many CI to fail. This causes unnecessary noise and maintenance burden, given that those errors are often fixed after a small time, when the link host/maintainer fixes/renew their certificate.
Describe the solution you'd like
There should be an option to allow ignoring certain websites for SSL error (either globally, on a per-host, or regex basis). When enabled, an SSL error would retry the request using HTTP. If it still fails, then broken should be reported as it currently does. Otherwise, the link is silently permitted.
Describe alternatives you've considered
The workaround is either to ignore the broken site link (entirely!) or to switch the link back to HTTP instead of HTTPS. The first workaround could potentially mask and actual invalid link error at a later time. The second is not as much of a drastic issue, but causes documentation to redirect users to unprotected sites. Typically, browsers are able to handle SSL error and still display the HTTPS site content, so HTTPS links should be preferred (with the hope that SSL certificate would be fixed in a near future).
Additional context
Related but different:
- #9592
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Begin with the linkcheck entry point and its configuration and tests; the issue does not name specific files, so trace how SSL failures are currently reported. Done means an option can selectively permit SSL failures, retry over HTTP, and still report the link as broken when the HTTP retry fails, with coverage for the chosen matching scope.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100