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.

3 files changed, 47 insertions, 3 deletions

diff --git a/docs/conf.py b/docs/conf.py
index 24934503c9..3166397e30 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -50,6 +50,28 @@ extensions = [
 autosectionlabel_prefix_document = True
 autosectionlabel_maxdepth = 2
 
+# Linkcheck settings.
+linkcheck_ignore = [
+    # Special-use addresses and domain names. (RFC 6761/6890)
+    r'^https?://(?:127\.0\.0\.1|\[::1\])(?::\d+)?/',
+    r'^https?://(?:[^/\.]+\.)*example\.(?:com|net|org)(?::\d+)?/',
+    r'^https?://(?:[^/\.]+\.)*(?:example|invalid|localhost|test)(?::\d+)?/',
+    # Pages that are inaccessible because they require authentication.
+    r'^https://github\.com/[^/]+/[^/]+/fork',
+    r'^https://code\.djangoproject\.com/github/login',
+    r'^https://code\.djangoproject\.com/newticket',
+    r'^https://(?:code|www)\.djangoproject\.com/admin/',
+    r'^https://www\.djangoproject\.com/community/add/blogs/',
+    r'^https://www\.google\.com/webmasters/tools/ping',
+    r'^https://search\.google\.com/search-console/welcome',
+    # Fragments used to dynamically switch content or populate fields.
+    r'^https://webchat\.freenode\.net/#',
+    r'^https://github\.com/[^#]+#L\d+-L\d+$',
+    r'^https://help\.apple\.com/itc/podcasts_connect/#/itc',
+    # Anchors on certain pages with missing a[name] attributes.
+    r'^https://tools\.ietf\.org/html/rfc1123\.html#section-',
+]
+
 # Spelling check needs an additional module that is not installed by default.
 # Add it only if spelling check is requested so docs can be generated without it.
 if 'spelling' in sys.argv:
diff --git a/docs/internals/contributing/writing-documentation.txt b/docs/internals/contributing/writing-documentation.txt
index 0cea608191..813cc028a2 100644
--- a/docs/internals/contributing/writing-documentation.txt
+++ b/docs/internals/contributing/writing-documentation.txt
@@ -510,6 +510,28 @@ one of the following:
 * If, and only if, you are sure the word you are using is correct - add it
   to ``docs/spelling_wordlist`` (please keep the list in alphabetical order).
 
+.. _documentation-link-check:
+
+Link check
+==========
+
+Links in documentation can become broken or changed such that they are no
+longer the canonical link. Sphinx provides a builder that can check whether the
+links in the documentation are working. From the ``docs`` directory, run ``make
+linkcheck``. Output is printed to the terminal, but can also be found in
+``_build/linkcheck/output.txt`` and ``_build/linkcheck/output.json``.
+
+Entries that have a status of "working" are fine, those that are "unchecked" or
+"ignored" have been skipped because they either cannot be checked or have
+matched ignore rules in the configuration.
+
+Entries that have a status of "broken" need to be fixed. Those that have a
+status of "redirected" may need to be updated to point to the canonical
+location, e.g. the scheme has changed ``http://`` → ``https://``. In certain
+cases, we do not want to update a "redirected" link, e.g. a rewrite to always
+point to the latest or stable version of documentation, e.g. ``/en/stable/`` →
+``/en/3.2/``.
+
 Translating documentation
 =========================
 
diff --git a/docs/internals/howto-release-django.txt b/docs/internals/howto-release-django.txt
index beb3581d54..078b31a472 100644
--- a/docs/internals/howto-release-django.txt
+++ b/docs/internals/howto-release-django.txt
@@ -103,9 +103,9 @@ any time leading up to the actual release:
 #. Check with the other committers to make sure they don't have any
    uncommitted changes for the release.
 
-#. Proofread the release notes, including looking at the online
-   version to catch any broken links or reST errors, and make sure the
-   release notes contain the correct date.
+#. Proofread the release notes, including looking at the online version to
+   :ref:`catch any broken links <documentation-link-check>` or reST errors, and
+   make sure the release notes contain the correct date.
 
 #. Double-check that the release notes mention deprecation timelines
    for any APIs noted as deprecated, and that they mention any changes