sphinx-doc / sphinx-doc/sphinx

Option to ignore `linkcheck` for SSL error

Open
#12,985 11 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

builder:linkcheck type:proposal
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.