Fixed #32720 -- Added configuration and docs for Sphinx link checker.

docs/conf.py

@@ -18,7 +18,7 @@
 #
 # Python's default allowed recursion depth is 1000 but this isn't enough for
 # building docs/ref/settings.txt sometimes.
-# https://groups.google.com/d/topic/sphinx-dev/MtRf64eGtv4/discussion
+# https://groups.google.com/g/sphinx-dev/c/MtRf64eGtv4/discussion
 sys.setrecursionlimit(2000)
 
 # Make sure we get the version of this copy of Django
@@ -50,6 +50,28 @@
 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:

docs/faq/general.txt

@@ -172,7 +172,7 @@ site is one module of Django the framework. Furthermore, although Django has
 special conveniences for building "CMS-y" apps, that doesn't mean it's not just
 as appropriate for building "non-CMS-y" apps (whatever that means!).
 
-.. _Drupal: https://drupal.org/
+.. _Drupal: https://www.drupal.org/
 
 How can I download the Django documentation to read it offline?
 ===============================================================
@@ -197,7 +197,7 @@ software are still a matter of some debate.
 
 For example, `APA style`_,  would dictate something like::
 
-    Django (Version 1.5) [Computer Software]. (2013). Retrieved from https://djangoproject.com.
+    Django (Version 1.5) [Computer Software]. (2013). Retrieved from https://www.djangoproject.com/.
 
 However, the only true guide is what your publisher will accept, so get a copy
 of those guidelines and fill in the gaps as best you can.
@@ -207,11 +207,11 @@ Foundation".
 
 If you need a publishing location, use "Lawrence, Kansas".
 
-If you need a web address, use https://djangoproject.com.
+If you need a web address, use https://www.djangoproject.com/.
 
 If you need a name, just use "Django", without any tagline.
 
 If you need a publication date, use the year of release of the version you're
 referencing (e.g., 2013 for v1.5)
 
-.. _APA style: https://www.apastyle.org
+.. _APA style: https://apastyle.apa.org/

docs/howto/auth-remote-user.txt

@@ -12,7 +12,7 @@ Windows Authentication or Apache and `mod_authnz_ldap`_, `CAS`_, `Cosign`_,
 .. _mod_authnz_ldap: https://httpd.apache.org/docs/2.2/mod/mod_authnz_ldap.html
 .. _CAS: https://www.apereo.org/projects/cas
 .. _Cosign: http://weblogin.org
-.. _WebAuth: https://www.stanford.edu/services/webauth/
+.. _WebAuth: https://uit.stanford.edu/service/authentication
 .. _mod_auth_sspi: https://sourceforge.net/projects/mod-auth-sspi
 
 When the Web server takes care of authentication it typically sets the

docs/howto/custom-template-backend.txt

@@ -170,4 +170,4 @@ creating an object that specifies the following attributes:
   to load the template, e.g. ``django.template.loaders.filesystem.Loader``.
 
 .. _DEP 182: https://github.com/django/deps/blob/main/final/0182-multiple-template-engines.rst
-.. _Django Debug Toolbar: https://github.com/jazzband/django-debug-toolbar
+.. _Django Debug Toolbar: https://github.com/jazzband/django-debug-toolbar/

docs/howto/deployment/wsgi/modwsgi.txt

@@ -27,7 +27,7 @@ Basic configuration
 Once you've got mod_wsgi installed and activated, edit your Apache server's
 `httpd.conf`_ file and add the following.
 
-.. _httpd.conf: https://wiki.apache.org/httpd/DistrosDefaultLayout
+.. _httpd.conf: https://cwiki.apache.org/confluence/display/httpd/DistrosDefaultLayout
 
 .. code-block:: apache
 

docs/howto/outputting-pdf.txt

@@ -15,7 +15,7 @@ printer-friendly NCAA tournament brackets, as PDF files, for people
 participating in a March Madness contest.
 
 .. _ReportLab: https://www.reportlab.com/opensource/
-.. _kusports.com: http://www.kusports.com/
+.. _kusports.com: http://www2.kusports.com/
 
 Install ReportLab
 =================

docs/howto/windows.txt

@@ -22,7 +22,7 @@ Install Python
 Django is a Python web framework, thus requiring Python to be installed on your
 machine. At the time of writing, Python 3.8 is the latest version.
 
-To install Python on your machine go to https://python.org/downloads/. The
+To install Python on your machine go to https://www.python.org/downloads/. The
 website should offer you a download button for the latest Python version.
 Download the executable installer and run it. Check the boxes next to "Install
 launcher for all users (recommended)" then click "Install Now".

docs/internals/contributing/committing-code.txt

@@ -138,7 +138,7 @@ Django's Git repository:
   Credit the contributors in the commit message: "Thanks A for the report and B
   for review." Use git's `Co-Authored-By`_ as appropriate.
 
-  .. _Co-Authored-By: https://help.github.com/articles/creating-a-commit-with-multiple-authors/
+  .. _Co-Authored-By: https://docs.github.com/en/github/committing-changes-to-your-project/creating-a-commit-with-multiple-authors
 
 * For commits to a branch, prefix the commit message with the branch name.
   For example: "[1.4.x] Fixed #xxxxx -- Added support for mind reading."

docs/internals/contributing/writing-code/unit-tests.txt

@@ -142,7 +142,7 @@ Running tests using ``django-docker-box``
 supported databases and python versions. See the `django-docker-box`_ project
 page for installation and usage instructions.
 
-.. _django-docker-box: https://github.com/django/django-docker-box
+.. _django-docker-box: https://github.com/django/django-docker-box/
 
 .. _running-unit-tests-settings:
 
@@ -320,13 +320,13 @@ associated tests will be skipped.
 To run some of the autoreload tests, you'll need to install the Watchman_
 service.
 
-.. _argon2-cffi: https://pypi.org/project/argon2_cffi/
+.. _argon2-cffi: https://pypi.org/project/argon2-cffi/
 .. _asgiref: https://pypi.org/project/asgiref/
 .. _bcrypt: https://pypi.org/project/bcrypt/
 .. _colorama: https://pypi.org/project/colorama/
 .. _docutils: https://pypi.org/project/docutils/
 .. _geoip2: https://pypi.org/project/geoip2/
-.. _jinja2: https://pypi.org/project/jinja2/
+.. _jinja2: https://pypi.org/project/Jinja2/
 .. _numpy: https://pypi.org/project/numpy/
 .. _Pillow: https://pypi.org/project/Pillow/
 .. _PyYAML: https://pyyaml.org/wiki/PyYAML

docs/internals/contributing/writing-documentation.txt

@@ -61,7 +61,7 @@ To get started contributing, you'll want to read the :ref:`reStructuredText
 reference <sphinx:rst-index>`.
 
 Your locally-built documentation will be themed differently than the
-documentation at `docs.djangoproject.com <https://docs.djangoproject.com>`_.
+documentation at `docs.djangoproject.com <https://docs.djangoproject.com/>`_.
 This is OK! If your changes look good on your local machine, they'll look good
 on the website.
 
@@ -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
 =========================
 

docs/internals/git.txt

@@ -50,7 +50,7 @@ website can be found at `github.com/django/djangoproject.com
 <https://github.com/django/djangoproject.com>`_.
 
 .. _Git: https://git-scm.com/
-.. _documentation: https://git-scm.com/documentation
+.. _documentation: https://git-scm.com/doc
 .. _branches: https://github.com/django/django/branches
 .. _tags: https://github.com/django/django/tags
 

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
@@ -337,7 +337,7 @@ Now you're ready to actually put the release out there. To do this:
    that they install correctly, but it'll catch silly mistakes.
 
 #. Ask a few people on IRC to verify the checksums by visiting the checksums
-   file (e.g. https://www.djangoproject.com/m/pgp/Django-1.5b1.checksum.txt)
+   file (e.g. https://media.djangoproject.com/pgp/Django-1.5b1.checksum.txt)
    and following the instructions in it. For bonus points, they can also unpack
    the downloaded release tarball and verify that its contents appear to be
    correct (proper version numbers, no stray ``.pyc`` or other undesirable
@@ -451,8 +451,8 @@ need to be done by the releaser.
    <https://readthedocs.org/projects/django/>`_. Since the automatically
    generated version names ("stable-A.B.x") differ from the version names
    used in Read the Docs ("A.B.x"), `create a ticket
-   <https://github.com/rtfd/readthedocs.org/issues/5537>`_ requesting the new
-   version.
+   <https://github.com/readthedocs/readthedocs.org/issues/5537>`_ requesting
+   the new version.
 
 #. `Request the new classifier on PyPI
    <https://github.com/pypa/trove-classifiers/issues/29>`_. For example

docs/internals/mailing-lists.txt

@@ -31,7 +31,7 @@ installation, usage, or debugging of Django.
 * `django-users subscription email address`_
 * `django-users posting email`_
 
-.. _django-users mailing archive: https://groups.google.com/d/forum/django-users
+.. _django-users mailing archive: https://groups.google.com/g/django-users
 .. _django-users subscription email address: mailto:django-users+subscribe@googlegroups.com
 .. _django-users posting email: mailto:django-users@googlegroups.com
 
@@ -48,7 +48,7 @@ the Django Project.
 * `django-core-mentorship subscription email address`_
 * `django-core-mentorship posting email`_
 
-.. _django-core-mentorship mailing archive: https://groups.google.com/d/forum/django-core-mentorship
+.. _django-core-mentorship mailing archive: https://groups.google.com/g/django-core-mentorship
 .. _django-core-mentorship subscription email address: mailto:django-core-mentorship+subscribe@googlegroups.com
 .. _django-core-mentorship posting email: mailto:django-core-mentorship@googlegroups.com
 
@@ -73,7 +73,7 @@ answered there.
 * `django-developers subscription email address`_
 * `django-developers posting email`_
 
-.. _django-developers mailing archive: https://groups.google.com/d/forum/django-developers
+.. _django-developers mailing archive: https://groups.google.com/g/django-developers
 .. _django-developers subscription email address: mailto:django-developers+subscribe@googlegroups.com
 .. _django-developers posting email: mailto:django-developers@googlegroups.com
 
@@ -89,7 +89,7 @@ Django's components.
 * `django-i18n subscription email address`_
 * `django-i18n posting email`_
 
-.. _django-i18n mailing archive: https://groups.google.com/d/forum/django-i18n
+.. _django-i18n mailing archive: https://groups.google.com/g/django-i18n
 .. _django-i18n subscription email address: mailto:django-i18n+subscribe@googlegroups.com
 .. _django-i18n posting email: mailto:django-i18n@googlegroups.com
 
@@ -105,7 +105,7 @@ A (very) low-traffic list for announcing :ref:`upcoming security releases
 * `django-announce subscription email address`_
 * `django-announce posting email`_
 
-.. _django-announce mailing archive: https://groups.google.com/d/forum/django-announce
+.. _django-announce mailing archive: https://groups.google.com/g/django-announce
 .. _django-announce subscription email address: mailto:django-announce+subscribe@googlegroups.com
 .. _django-announce posting email: mailto:django-announce@googlegroups.com
 
@@ -121,6 +121,6 @@ by developers and interested community members.
 * `django-updates subscription email address`_
 * `django-updates posting email`_
 
-.. _django-updates mailing archive: https://groups.google.com/d/forum/django-updates
+.. _django-updates mailing archive: https://groups.google.com/g/django-updates
 .. _django-updates subscription email address: mailto:django-updates+subscribe@googlegroups.com
 .. _django-updates posting email: mailto:django-updates@googlegroups.com

docs/intro/contributing.txt

@@ -343,7 +343,7 @@ This test checks that the ``make_toast()`` returns ``'toast'``.
     * After reading those, if you want something a little meatier to sink
       your teeth into, there's always the Python :mod:`unittest` documentation.
 
-__ https://www.diveinto.org/python3/unit-testing.html
+__ https://diveinto.org/python3/unit-testing.html
 
 Running your new test
 ---------------------

docs/intro/index.txt

@@ -34,7 +34,7 @@ place: read this material to quickly get up and running.
     Python quickly, we recommend `Dive Into Python`_. If that's not quite your
     style, there are many other `books about Python`_.
 
-    .. _python: https://python.org/
+    .. _python: https://www.python.org/
     .. _list of Python resources for non-programmers: https://wiki.python.org/moin/BeginnersGuide/NonProgrammers
     .. _Dive Into Python: https://diveinto.org/python3/table-of-contents.html
     .. _books about Python: https://wiki.python.org/moin/PythonBooks

docs/intro/install.txt

@@ -14,7 +14,7 @@ Being a Python Web framework, Django requires Python. See
 :ref:`faq-python-version-support` for details. Python includes a lightweight
 database called SQLite_ so you won't need to set up a database just yet.
 
-.. _sqlite: https://sqlite.org/
+.. _sqlite: https://www.sqlite.org/
 
 Get the latest version of Python at https://www.python.org/downloads/ or with
 your operating system's package manager.

docs/intro/tutorial03.txt

@@ -212,7 +212,7 @@ Put the following code in that template:
     To make the tutorial shorter, all template examples use incomplete HTML. In
     your own projects you should use `complete HTML documents`__.
 
-__ https://developer.mozilla.org/en-US/docs/Learn/HTML/Introduction_to_HTML/Getting_started#Anatomy_of_an_HTML_document
+__ https://developer.mozilla.org/en-US/docs/Learn/HTML/Introduction_to_HTML/Getting_started#anatomy_of_an_html_document
 
 Now let's update our ``index`` view in ``polls/views.py`` to use the template:
 

docs/intro/tutorial05.txt

@@ -689,7 +689,7 @@ Coverage will help to identify dead code. See
 :doc:`Testing in Django </topics/testing/index>` has comprehensive
 information about testing.
 
-.. _Selenium: http://seleniumhq.org/
+.. _Selenium: https://www.selenium.dev/
 .. _continuous integration: https://en.wikipedia.org/wiki/Continuous_integration
 
 What's next?

docs/ref/class-based-views/base.txt

@@ -225,7 +225,7 @@ MRO is an acronym for Method Resolution Order.
         urlpatterns = [
             path('counter/<int:pk>/', ArticleCounterRedirectView.as_view(), name='article-counter'),
             path('details/<int:pk>/', ArticleDetailView.as_view(), name='article-detail'),
-            path('go-to-django/', RedirectView.as_view(url='https://djangoproject.com'), name='go-to-django'),
+            path('go-to-django/', RedirectView.as_view(url='https://www.djangoproject.com/'), name='go-to-django'),
         ]
 
     **Attributes**

docs/ref/clickjacking.txt

@@ -132,5 +132,5 @@ See also
 
 A `complete list`_ of browsers supporting ``X-Frame-Options``.
 
-.. _complete list: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options#Browser_compatibility
+.. _complete list: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options#browser_compatibility
 .. _other clickjacking prevention techniques: https://en.wikipedia.org/wiki/Clickjacking#Prevention

docs/ref/contrib/gis/db-api.txt

@@ -401,7 +401,7 @@ Aggregate                PostGIS  Oracle  SpatiaLite
 =======================  =======  ======  ==========
 
 .. rubric:: Footnotes
-.. [#fnwkt] *See* Open Geospatial Consortium, Inc., `OpenGIS Simple Feature Specification For SQL <http://www.opengis.org/docs/99-049.pdf>`_, Document 99-049 (May 5, 1999), at  Ch. 3.2.5, p. 3-11 (SQL Textual Representation of Geometry).
+.. [#fnwkt] *See* Open Geospatial Consortium, Inc., `OpenGIS Simple Feature Specification For SQL <https://portal.ogc.org/files/?artifact_id=829>`_, Document 99-049 (May 5, 1999), at  Ch. 3.2.5, p. 3-11 (SQL Textual Representation of Geometry).
 .. [#fnewkb] *See* `PostGIS EWKB, EWKT and Canonical Forms <https://postgis.net/docs/using_postgis_dbmanagement.html#EWKB_EWKT>`_, PostGIS documentation at Ch. 4.1.2.
 .. [#fndistsphere15] *See* `PostGIS documentation <https://postgis.net/docs/ST_DistanceSphere.html>`_ on ``ST_DistanceSphere``.
 .. [#] Refer :ref:`mysql-spatial-limitations` section for more details.

docs/ref/contrib/gis/gdal.txt

@@ -21,7 +21,7 @@ to raster (image) data.
     Although the module is named ``gdal``, GeoDjango only supports some of the
     capabilities of OGR and GDAL's raster features at this time.
 
-__ https://www.gdal.org/
+__ https://gdal.org/
 __ https://gdal.org/user/vector_data_model.html
 
 Overview
@@ -1644,7 +1644,7 @@ Examples of using the different keys when creating rasters can be found in the
 documentation of the corresponding attributes and methods of the
 :class:`GDALRaster` and :class:`GDALBand` classes.
 
-__ https://geojson.org
+__ https://geojson.org/
 
 The ``ds_input`` dictionary
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/ref/contrib/gis/geoip2.txt

@@ -20,7 +20,7 @@ that ``geoip2`` can leverage the C library's faster speed.
 __ https://geoip2.readthedocs.io/
 __ https://pypi.org/project/geoip2/
 __ https://dev.maxmind.com/geoip/geoip2/geolite2/
-__ https://github.com/maxmind/libmaxminddb
+__ https://github.com/maxmind/libmaxminddb/
 
 Example
 =======

docs/ref/contrib/gis/geoquerysets.txt

@@ -935,7 +935,7 @@ Example::
     >>> u = Zipcode.objects.filter(poly__within=bbox).aggregate(Union(poly))  # A more sensible approach.
 
 .. rubric:: Footnotes
-.. [#fnde9im] *See* `OpenGIS Simple Feature Specification For SQL <http://www.opengis.org/docs/99-049.pdf>`_, at Ch. 2.1.13.2, p. 2-13 (The Dimensionally Extended Nine-Intersection Model).
+.. [#fnde9im] *See* `OpenGIS Simple Feature Specification For SQL <https://portal.ogc.org/files/?artifact_id=829>`_, at Ch. 2.1.13.2, p. 2-13 (The Dimensionally Extended Nine-Intersection Model).
 .. [#fnsdorelate] *See* `SDO_RELATE documentation <https://docs.oracle.com/en/
    database/oracle/oracle-database/18/spatl/spatial-operators-reference.html#
    GUID-97C17C18-F05E-49B4-BE11-E89B972E2A02>`_, from the Oracle Spatial and

docs/ref/contrib/gis/geos.txt

@@ -19,7 +19,7 @@ maintained by `Refractions Research`__ of Victoria, Canada.
 
 __ https://trac.osgeo.org/geos/
 __ https://sourceforge.net/projects/jts-topo-suite/
-__ https://www.opengeospatial.org/standards/sfs
+__ https://www.ogc.org/standards/sfs
 __ http://www.refractions.net/
 
 Features