Opened 4 years ago

Closed 3 years ago

Last modified 3 years ago

#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 Nick Pope)

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.
  2. 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 Mariusz Felisiak, 4 years ago

Triage Stage: UnreviewedAccepted

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".

comment:2 by Nick Pope, 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 Mariusz Felisiak, 3 years ago

Triage Stage: AcceptedReady for checkin

comment:4 by Mariusz Felisiak <felisiak.mariusz@…>, 3 years ago

In 8c4caee7:

Refs #32720 -- Used :commit: and :source: role in old release notes.

comment:5 by Mariusz Felisiak <felisiak.mariusz@…>, 3 years ago

In 1c3bbcf:

Refs #32720 -- Used full hashes in security archive.

comment:6 by Mariusz Felisiak <felisiak.mariusz@…>, 3 years ago

In 7c4ee48:

Refs #32720 -- Fixed some broken links in docs.

comment:7 by Mariusz Felisiak <felisiak.mariusz@…>, 3 years ago

In c156e369:

Refs #32720 -- Updated various links in docs to avoid redirects and use HTTPS.

comment:8 by Mariusz Felisiak <felisiak.mariusz@…>, 3 years ago

Resolution: fixed
Status: assignedclosed

In 0851933:

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.

comment:9 by Mariusz Felisiak <felisiak.mariusz@…>, 3 years ago

In 80cf193:

[3.2.x] Refs #32720 -- Used :commit: and :source: role in old release notes.

Backport of 8c4caee76a5571c6c8050660a6a9fc30ece6678d from main

comment:10 by Mariusz Felisiak <felisiak.mariusz@…>, 3 years ago

In 0c19b075:

[3.2.x] Refs #32720 -- Used full hashes in security archive.

Backport of 1c3bbcf802e661fc599365a097532ed3b362d16b from main

comment:11 by Mariusz Felisiak <felisiak.mariusz@…>, 3 years ago

In 55b89e8:

[3.2.x] Refs #32720 -- Fixed some broken links in docs.

Backport of 7c4ee487c7392a3a394caf62efad355fad639655 from main

comment:12 by Mariusz Felisiak <felisiak.mariusz@…>, 3 years ago

In cb91b2d:

[3.2.x] Refs #32720 -- Updated various links in docs to avoid redirects and use HTTPS.

Backport of c156e369553c75a30c78b8ed54a57b1101865105 from main

Note: See TracTickets for help on using tickets.
Back to Top