From 10dfa08f5a67e0e7228a1ccd2c515e8c3537ed4f Mon Sep 17 00:00:00 2001 From: Nick Pope Date: Thu, 6 May 2021 16:09:30 +0100 Subject: [PATCH] Refs #32720 -- Added documentation for Sphinx linkcheck builder. --- .../contributing/writing-documentation.txt | 25 +++++++++++++++++++ docs/internals/howto-release-django.txt | 3 ++- 2 files changed, 27 insertions(+), 1 deletion(-) diff --git a/docs/internals/contributing/writing-documentation.txt b/docs/internals/contributing/writing-documentation.txt index 5addd46fbb001..5dc40934eef85 100644 --- a/docs/internals/contributing/writing-documentation.txt +++ b/docs/internals/contributing/writing-documentation.txt @@ -510,6 +510,31 @@ 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`` or, if you need to process the output, you can +use ``_build/linkcheck/output.json`` which is in `JSON Lines`__ format.. + +__ https://jsonlines.org/ + +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..6fb806324a0ad 100644 --- a/docs/internals/howto-release-django.txt +++ b/docs/internals/howto-release-django.txt @@ -105,7 +105,8 @@ any time leading up to the actual 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. + release notes contain the correct date. (Use the `linkcheck builder + `_ to assist with checking for broken links.) #. Double-check that the release notes mention deprecation timelines for any APIs noted as deprecated, and that they mention any changes