From 6015bab80e28aef2669f6fac53423aa65f70cb08 Mon Sep 17 00:00:00 2001 From: Mariusz Felisiak Date: Tue, 28 Feb 2023 13:14:51 +0100 Subject: 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 --- docs/Makefile | 8 ++++++++ .../contributing/writing-code/submitting-patches.txt | 6 +++--- docs/internals/contributing/writing-code/unit-tests.txt | 11 ++++++----- docs/internals/contributing/writing-documentation.txt | 10 ++++++++++ docs/make.bat | 9 +++++++++ docs/requirements.txt | 1 + 6 files changed, 37 insertions(+), 8 deletions(-) (limited to 'docs') 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 ` conform to our - guidelines? Are there any ``black``, ``flake8``, or ``isort`` errors? You - can install the :ref:`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 + ` 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:: `. +.. 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 -- cgit v1.3