Refs #34140 -- Added configurations to run blacken-docs linter and adjusted docs.

This adds:
- GitHub actions,
- tox configuration,
- pre-commit hook, and
- makefile rules
to run blacken-docs linter.

Co-authored-by: David Smith <smithdc@gmail.com>

6 files changed, 37 insertions, 8 deletions

diff --git a/docs/Makefile b/docs/Makefile
index 2b44830531..d97a7ff07c 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -49,6 +49,7 @@ help:
 	@echo "  linkcheck  to check all external links for integrity"
 	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
 	@echo "  spelling   to check for typos in documentation"
+	@echo "  black      to apply the black formatting to code blocks in documentation"
 
 
 clean:
@@ -165,3 +166,10 @@ spelling:
 	@echo
 	@echo "Check finished. Wrong words can be found in " \
 		"$(BUILDDIR)/spelling/output.txt."
+
+black:
+	@mkdir -p $(BUILDDIR)/black
+	find -name "*.txt" -not -path "./_build/*" -not -path "./_theme/*" \
+		| xargs blacken-docs --rst-literal-block; echo $$? > "$(BUILDDIR)/black/output.txt"
+	@echo
+	@echo "Code blocks reformatted"
diff --git a/docs/internals/contributing/writing-code/submitting-patches.txt b/docs/internals/contributing/writing-code/submitting-patches.txt
index 0ab3e27def..14cb2ef2fa 100644
--- a/docs/internals/contributing/writing-code/submitting-patches.txt
+++ b/docs/internals/contributing/writing-code/submitting-patches.txt
@@ -291,9 +291,9 @@ All code changes
 
 * Does the :doc:`coding style
   </internals/contributing/writing-code/coding-style>` conform to our
-  guidelines? Are there any  ``black``, ``flake8``, or ``isort`` errors? You
-  can install the :ref:`pre-commit <coding-style-pre-commit>` hooks to
-  automatically catch these errors.
+  guidelines? Are there any  ``black``, ``blacken-docs``, ``flake8``, or
+  ``isort`` errors? You can install the :ref:`pre-commit
+  <coding-style-pre-commit>` hooks to automatically catch these errors.
 * If the change is backwards incompatible in any way, is there a note
   in the release notes (``docs/releases/A.B.txt``)?
 * Is Django's test suite passing?
diff --git a/docs/internals/contributing/writing-code/unit-tests.txt b/docs/internals/contributing/writing-code/unit-tests.txt
index b547a28049..8789e0ef7b 100644
--- a/docs/internals/contributing/writing-code/unit-tests.txt
+++ b/docs/internals/contributing/writing-code/unit-tests.txt
@@ -69,17 +69,18 @@ command from any place in the Django source tree:
     $ tox
 
 By default, ``tox`` runs the test suite with the bundled test settings file for
-SQLite, ``black``, ``flake8``, ``isort``, and the documentation spelling
-checker. In addition to the system dependencies noted elsewhere in this
-documentation, the command ``python3`` must be on your path and linked to the
-appropriate version of Python. A list of default environments can be seen as
-follows:
+SQLite, ``black``, ``blacken-docs``, ``flake8``, ``isort``, and the
+documentation spelling checker. In addition to the system dependencies noted
+elsewhere in this documentation, the command ``python3`` must be on your path
+and linked to the appropriate version of Python. A list of default environments
+can be seen as follows:
 
 .. console::
 
     $ tox -l
     py3
     black
+    blacken-docs
     flake8>=3.7.0
     docs
     isort>=5.1.0
diff --git a/docs/internals/contributing/writing-documentation.txt b/docs/internals/contributing/writing-documentation.txt
index a89ea050d5..3e6b846a7a 100644
--- a/docs/internals/contributing/writing-documentation.txt
+++ b/docs/internals/contributing/writing-documentation.txt
@@ -211,6 +211,9 @@ 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 `blacken-docs`_
+  auto-formatter. This will be run by ``pre-commit`` if that is configured.
+
 * Use :mod:`~sphinx.ext.intersphinx` to reference Python's and Sphinx'
   documentation.
 
@@ -258,6 +261,13 @@ documentation:
   also need to define a reference to the documentation for that environment
   variable using :rst:dir:`.. envvar:: <envvar>`.
 
+.. versionchanged:: 4.2
+
+    All Python code blocks in the Django documentation were reformatted with
+    `blacken-docs`_.
+
+.. _blacken-docs: https://pypi.org/project/blacken-docs/
+
 Django-specific markup
 ======================
 
diff --git a/docs/make.bat b/docs/make.bat
index 4743692ca3..72d71136c2 100644
--- a/docs/make.bat
+++ b/docs/make.bat
@@ -35,6 +35,7 @@ if "%1" == "help" (
 	echo.  linkcheck  to check all external links for integrity
 	echo.  doctest    to run all doctests embedded in the documentation if enabled
 	echo.  spelling   to check for typos in documentation
+	echo.  black      to apply the black formatting to code blocks in documentation
 	goto end
 )
 
@@ -196,4 +197,12 @@ spelling/output.txt.
 	goto end
 )
 
+if "%1" == "black" (
+	for /f "usebackq tokens=*" %%i in (`dir *.txt /s /b ^| findstr /v /c:"_build" /c:"_theme"`) do (
+		blacken-docs --rst-literal-block %%i
+	)
+	echo.
+	echo.Code blocks reformatted
+)
+
 :end
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 344d3bcc8c..e234972a3b 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,3 +1,4 @@
 pyenchant
 Sphinx>=4.5.0
 sphinxcontrib-spelling
+blacken-docs