#32720: Add configuration for Sphinx linkcheck builder.
-------------------------------------+-------------------------------------
Reporter: Nick Pope | Owner: Nick Pope
Type: | Status: assigned
Cleanup/optimization |
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: linkcheck | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Old 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:
>
> 1. Add some initial configuration and documentation, fix broken links,
> and "canonicalize" some links to avoid redirects.
> 1. 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 [https://github.com/sphinx-
> doc/sphinx/issues/6525 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 [https://github.com/django/django/pull/14325 PR] for the first
> step.
New 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:
1. Add some initial configuration and documentation, fix broken links, and
"canonicalize" some links to avoid redirects.
1. ~~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 [https://github.com/sphinx-
doc/sphinx/issues/6525 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 [https://github.com/django/django/pull/14325 PR]~~ for the first
step~~.
(Migrated suggestion for a scheduled GitHub action to #32723.)
--
Comment (by Nick Pope):
Replying to [comment:1 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.
--
Ticket URL: <https://code.djangoproject.com/ticket/32720#comment:2>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To view this discussion on the web visit
https://groups.google.com/d/msgid/django-updates/065.421280687aeef2cf5d34257507e55a2b%40djangoproject.com.
