Opened 4 years ago
Last modified 4 years ago
#32720 closed Cleanup/optimization
Add configuration for Sphinx linkcheck builder. — at Initial Version
Reported by: | Nick Pope | Owned by: | Nick Pope |
---|---|---|---|
Component: | Documentation | Version: | dev |
Severity: | Normal | Keywords: | linkcheck |
Cc: | Triage Stage: | Ready for checkin | |
Has patch: | yes | Needs documentation: | no |
Needs tests: | no | Patch needs improvement: | no |
Easy pickings: | yes | UI/UX: | no |
Description
It would be helpful to configure the linkcheck
builder for Sphinx.
I found a single reference to this being used in the past in #8728, but links come and go all the time and need to be checked on an ongoing basis.
There are many benefits to running the link checker on a regular basis:
- Identify links that are broken and need to be fixed.
- Identify sites that are now redirecting to HTTPS where we want to use that instead of insecure links.
- Reduce the number of one-off requests to fix links when users come across them.
I propose the following steps:
- Add some initial configuration and documentation, fix broken links, and "canonicalize" some links to avoid redirects.
- Add a scheduled GitHub action to check for broken links, or redirects that could be simplified, on a weekly/monthly basis.
The second step would need to wait for sphinx-doc/sphinx#6525 to be addressed so that we can treat desired redirections as "working" links instead of "redirected", e.g. https://docs.djangoproject.com/en/stable/
→ https://docs.djangoproject.com/en/3.2/
.
The linkcheck
builder generates docs/_build/linkcheck/output.{json,txt}
which could be filtered and attached as an artifact from the GitHub action to make it easier to provide a report on what needs fixing.
Here's a PR for the first step.