[5.2.x] Refs #34140 -- Added dedicated code block formatting section in docs/internals/contributing/writing-documentation.txt.

Backport of cba73281966c816824c9bfa028a1bf44e188ded2 from main.

1 files changed, 19 insertions, 4 deletions

diff --git a/docs/internals/contributing/writing-documentation.txt b/docs/internals/contributing/writing-documentation.txt
index 10b7edbca8..f16cdc7cc7 100644
--- a/docs/internals/contributing/writing-documentation.txt
+++ b/docs/internals/contributing/writing-documentation.txt
@@ -177,6 +177,25 @@ 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-code-block-format-check:
+
+Code block format check
+-----------------------
+
+All Python code blocks should be formatted using the :pypi:`blacken-docs`
+auto-formatter. This is automatically run by the :ref:`pre-commit hook
+<coding-style-pre-commit>` if configured.
+
+The check can also be run manually: provided that ``blacken-docs`` is installed,
+run the following command from the ``docs`` directory:
+
+.. console::
+
+     $ make black
+
+The formatter will report any issues by printing them to the terminal and will
+reformat code blocks where possible.
+
 .. _documentation-link-check:
 
 Link check
@@ -305,10 +324,6 @@ documentation:
   "last bit" of that path. So ``:mod:`~django.contrib.auth``` will
   display a link with the title "auth".
 
-* All Python code blocks should be formatted using the :pypi:`blacken-docs`
-  auto-formatter. This will be run by :ref:`pre-commit
-  <coding-style-pre-commit>` if that is configured.
-
 * Use :mod:`~sphinx.ext.intersphinx` to reference Python's and Sphinx'
   documentation.