Add configuration for Sphinx linkcheck builder.

[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.)

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

[Nick Pope]

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.

[Mariusz Felisiak <felisiak.mariusz@…>]

In 8c4caee7:

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

[Mariusz Felisiak <felisiak.mariusz@…>]

In 1c3bbcf:

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

[Mariusz Felisiak <felisiak.mariusz@…>]

In 7c4ee48:

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

[Mariusz Felisiak <felisiak.mariusz@…>]

In c156e369:

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

[Mariusz Felisiak <felisiak.mariusz@…>]

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.

[Mariusz Felisiak <felisiak.mariusz@…>]

In 80cf193:

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

Backport of 8c4caee76a5571c6c8050660a6a9fc30ece6678d from main

[Mariusz Felisiak <felisiak.mariusz@…>]

In 0c19b075:

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

Backport of 1c3bbcf802e661fc599365a097532ed3b362d16b from main

[Mariusz Felisiak <felisiak.mariusz@…>]

In 55b89e8:

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

Backport of 7c4ee487c7392a3a394caf62efad355fad639655 from main

[Mariusz Felisiak <felisiak.mariusz@…>]

In cb91b2d:

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

Backport of c156e369553c75a30c78b8ed54a57b1101865105 from main