[Django] #32720: Add configuration for Sphinx linkcheck builder.
Django
-------------------------------------+-------------------------------------
Reporter: Nick Pope | Owner: Nick Pope
Type: | Status: assigned
Cleanup/optimization |
Component: | Version: dev
Documentation |
Severity: Normal | Keywords: linkcheck
Triage Stage: | Has patch: 1
Unreviewed |
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 1
UI/UX: 0 |
-------------------------------------+-------------------------------------
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.
--
Ticket URL: <https://code.djangoproject.com/ticket/32720>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
-------------------------------------+-------------------------------------
Reporter: Nick Pope | Owner: Nick Pope
Type: | Status: assigned
Cleanup/optimization |
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
-------------------------------------+-------------------------------------
* stage: Unreviewed => Accepted
Comment:
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".
--
Ticket URL: <https://code.djangoproject.com/ticket/32720#comment:1>
Django
-------------------------------------+-------------------------------------
Reporter: Nick Pope | Owner: Nick Pope
Type: | Status: assigned
Cleanup/optimization |
Severity: Normal | Resolution:
Keywords: linkcheck | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Old description:
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
-------------------------------------+-------------------------------------
Reporter: Nick Pope | Owner: Nick Pope
Type: | Status: assigned
Cleanup/optimization |
Severity: Normal | Resolution:
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
* stage: Accepted => Ready for checkin
--
Ticket URL: <https://code.djangoproject.com/ticket/32720#comment:3>
Django
-------------------------------------+-------------------------------------
Reporter: Nick Pope | Owner: Nick Pope
Cleanup/optimization |
Component: Documentation | Version: dev
Keywords: linkcheck | Triage Stage: Ready for
| checkin
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
* status: assigned => closed
* resolution: => fixed
Comment:
In [changeset:"0851933cba7b40e22f5e424c95763dbc27c40aa9" 0851933]:
{{{
#!CommitTicketReference repository=""
revision="0851933cba7b40e22f5e424c95763dbc27c40aa9"
Fixed #32720 -- Added configuration and docs for Sphinx link checker.
We explicitly ignore checking anchors for line-range anchors on GitHub
which are dynamically generated and, otherwise, show up as broken links.
See https://github.com/sphinx-
doc/sphinx/issues/7388#issuecomment-739961689.
We also ignore links to resources that require authentication.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/32720#comment:8>
Django
-------------------------------------+-------------------------------------
Reporter: Nick Pope | Owner: Nick Pope
Type: | Status: assigned
Cleanup/optimization |
Severity: Normal | Resolution:
| checkin
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Mariusz Felisiak <felisiak.mariusz@…>):
In [changeset:"8c4caee76a5571c6c8050660a6a9fc30ece6678d" 8c4caee7]:
{{{
#!CommitTicketReference repository=""
revision="8c4caee76a5571c6c8050660a6a9fc30ece6678d"
Refs #32720 -- Used :commit: and :source: role in old release notes.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/32720#comment:4>
Django
-------------------------------------+-------------------------------------
Reporter: Nick Pope | Owner: Nick Pope
Type: | Status: assigned
Cleanup/optimization |
Severity: Normal | Resolution:
Keywords: linkcheck | Triage Stage: Ready for
| checkin
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Mariusz Felisiak <felisiak.mariusz@…>):
In [changeset:"1c3bbcf802e661fc599365a097532ed3b362d16b" 1c3bbcf]:
{{{
#!CommitTicketReference repository=""
revision="1c3bbcf802e661fc599365a097532ed3b362d16b"
Refs #32720 -- Used full hashes in security archive.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/32720#comment:5>
Django
-------------------------------------+-------------------------------------
Reporter: Nick Pope | Owner: Nick Pope
Type: | Status: assigned
Cleanup/optimization |
Severity: Normal | Resolution:
Keywords: linkcheck | Triage Stage: Ready for
| checkin
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Mariusz Felisiak <felisiak.mariusz@…>):
In [changeset:"c156e369553c75a30c78b8ed54a57b1101865105" c156e369]:
{{{
#!CommitTicketReference repository=""
revision="c156e369553c75a30c78b8ed54a57b1101865105"
Refs #32720 -- Updated various links in docs to avoid redirects and use
HTTPS.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/32720#comment:7>
Django
-------------------------------------+-------------------------------------
Reporter: Nick Pope | Owner: Nick Pope
Type: | Status: assigned
Cleanup/optimization |
Severity: Normal | Resolution:
Keywords: linkcheck | Triage Stage: Ready for
| checkin
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Mariusz Felisiak <felisiak.mariusz@…>):
In [changeset:"7c4ee487c7392a3a394caf62efad355fad639655" 7c4ee48]:
{{{
#!CommitTicketReference repository=""
revision="7c4ee487c7392a3a394caf62efad355fad639655"
Refs #32720 -- Fixed some broken links in docs.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/32720#comment:6>
Django
-------------------------------------+-------------------------------------
Reporter: Nick Pope | Owner: Nick Pope
Cleanup/optimization |
Component: Documentation | Version: dev
Keywords: linkcheck | Triage Stage: Ready for
| checkin
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Mariusz Felisiak <felisiak.mariusz@…>):
In [changeset:"cb91b2d9e3e28d0ede24dbb052faa6e7fead5897" cb91b2d]:
{{{
#!CommitTicketReference repository=""
revision="cb91b2d9e3e28d0ede24dbb052faa6e7fead5897"
[3.2.x] Refs #32720 -- Updated various links in docs to avoid redirects
and use HTTPS.
Backport of c156e369553c75a30c78b8ed54a57b1101865105 from main
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/32720#comment:12>
Django
-------------------------------------+-------------------------------------
Reporter: Nick Pope | Owner: Nick Pope
Cleanup/optimization |
Component: Documentation | Version: dev
Severity: Normal | Resolution: fixed
Keywords: linkcheck | Triage Stage: Ready for
| checkin
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Mariusz Felisiak <felisiak.mariusz@…>):
In [changeset:"0c19b075b239bc99886979c9af706b18e634ed69" 0c19b075]:
{{{
#!CommitTicketReference repository=""
revision="0c19b075b239bc99886979c9af706b18e634ed69"
[3.2.x] Refs #32720 -- Used full hashes in security archive.
Backport of 1c3bbcf802e661fc599365a097532ed3b362d16b from main
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/32720#comment:10>
Django
-------------------------------------+-------------------------------------
Reporter: Nick Pope | Owner: Nick Pope
Cleanup/optimization |
Component: Documentation | Version: dev
Severity: Normal | Resolution: fixed
Keywords: linkcheck | Triage Stage: Ready for
| checkin
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Mariusz Felisiak <felisiak.mariusz@…>):
In [changeset:"55b89e8cac2f8cc7cf3f96dfa138b3b9fda81160" 55b89e8]:
{{{
#!CommitTicketReference repository=""
revision="55b89e8cac2f8cc7cf3f96dfa138b3b9fda81160"
[3.2.x] Refs #32720 -- Fixed some broken links in docs.
Backport of 7c4ee487c7392a3a394caf62efad355fad639655 from main
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/32720#comment:11>
Django
-------------------------------------+-------------------------------------
Reporter: Nick Pope | Owner: Nick Pope
Cleanup/optimization |
Component: Documentation | Version: dev
Severity: Normal | Resolution: fixed
Keywords: linkcheck | Triage Stage: Ready for
| checkin
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Mariusz Felisiak <felisiak.mariusz@…>):
In [changeset:"80cf193d32eae3a5250a5d195aefbb4fe9211d7a" 80cf193]:
{{{
#!CommitTicketReference repository=""
revision="80cf193d32eae3a5250a5d195aefbb4fe9211d7a"
[3.2.x] Refs #32720 -- Used :commit: and :source: role in old release
notes.
Backport of 8c4caee76a5571c6c8050660a6a9fc30ece6678d from main
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/32720#comment:9>