#32720 closed Cleanup/optimization (fixed)
Add configuration for Sphinx linkcheck builder.
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 (last modified by )
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.
(Migrated suggestion for a scheduled GitHub action to #32723.)
Change History (12)
comment:1 by , 4 years ago
Triage Stage: | Unreviewed → Accepted |
---|
comment:2 by , 4 years ago
Description: | modified (diff) |
---|
Replying to Mariusz Felisiak:
Thanks, I think adding the
linkcheck_ignore
configuration makes sense. I would leave a new GitHub action outside of this ticket, otherwise we would have to mark it as "someday/maybe".
Thanks Mariusz. I created #32723 for implementing a GitHub action in the future.
The linkcheck_ignore
now will at least help reduce the output that needs to be sifted through when running this manually in the interim.
comment:3 by , 3 years ago
Triage Stage: | Accepted → Ready for checkin |
---|
Thanks, I think adding the
linkcheck_ignore
configuration makes sense. I would leave a new GitHub action outside of this ticket, otherwise we would have to mark it as "someday/maybe".