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.