diff --git a/docs/conf.py b/docs/conf.py index 24934503c9eca..3166397e30dc2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -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: diff --git a/docs/internals/contributing/writing-documentation.txt b/docs/internals/contributing/writing-documentation.txt index 0cea608191f1b..813cc028a2963 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 beb3581d54fa5..c5bb4bd6d3106 100644 --- a/docs/internals/howto-release-django.txt +++ b/docs/internals/howto-release-django.txt @@ -104,8 +104,8 @@ any time leading up to the actual release: 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. + version to :ref:`catch any broken links ` 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