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>

.github/workflows/docs.yml

@@ -38,3 +38,24 @@ jobs:
         run: |
           cd docs
           sphinx-build -b spelling -n -q -W --keep-going -d _build/doctrees -D language=en_US -j auto . _build/spelling
+
+  blacken-docs:
+    runs-on: ubuntu-latest
+    name: blacken-docs
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+      - run: python -m pip install blacken-docs
+      - name: Build docs
+        run: |
+          cd docs
+          make black
+          RESULT=`cat _build/black/output.txt`
+          if [ "$RESULT" -gt 0 ]; then
+              echo "💥 📢 Code blocks in documentation must be reformatted with blacken-docs 📢 💥"
+          fi;
+          exit $RESULT

.pre-commit-config.yaml

@@ -4,6 +4,12 @@ repos:
     hooks:
     - id: black
       exclude: \.py-tpl$
+  - repo: https://github.com/adamchainz/blacken-docs
+    rev: 1.13.0
+    hooks:
+      - id: blacken-docs
+        additional_dependencies:
+        - black==23.1.0
   - repo: https://github.com/PyCQA/isort
     rev: 5.12.0
     hooks:

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"

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?

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

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
 ======================
 

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

docs/requirements.txt

@@ -1,3 +1,4 @@
 pyenchant
 Sphinx>=4.5.0
 sphinxcontrib-spelling
+blacken-docs

tox.ini

@@ -9,6 +9,7 @@ skipsdist = true
 envlist =
     py3
     black
+    blacken-docs
     flake8
     docs
     isort
@@ -39,6 +40,16 @@ deps = black
 changedir = {toxinidir}
 commands = black --check --diff .
 
+[testenv:blacken-docs]
+basepython = python3
+usedevelop = false
+allowlist_externals =
+    make
+deps = blacken-docs
+changedir = docs
+commands =
+    make black
+
 [testenv:flake8]
 basepython = python3
 usedevelop = false