diff --git a/docs/Makefile b/docs/Makefile index bbdd2bb4c8..9935ad09e5 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -174,3 +174,7 @@ black: | xargs blacken-docs --rst-literal-block; echo $$? > "$(BUILDDIR)/black/output.txt" @echo @echo "Code blocks reformatted" + +check: spelling black + @echo + @echo "Style and spelling checks completed." diff --git a/docs/internals/contributing/writing-documentation.txt b/docs/internals/contributing/writing-documentation.txt index bee0ee3886..1258d4686f 100644 --- a/docs/internals/contributing/writing-documentation.txt +++ b/docs/internals/contributing/writing-documentation.txt @@ -152,10 +152,29 @@ To edit this page, for example, we would edit the file :source:`docs/internals/contributing/writing-documentation.txt` and rebuild the HTML with ``make html``. +.. _documentation-checks: + +Documentation quality checks +---------------------------- + +Several checks help maintain Django's documentation quality, including +:ref:`spelling ` and +:ref:`code block formatting `. + +These checks are run automatically in CI and must pass before documentation +changes can be merged. They can also be run locally with a single command: + +.. console:: + + $ make check + +This command runs all current checks and will include any new checks added in +the future. + .. _documentation-spelling-check: Spelling check --------------- +~~~~~~~~~~~~~~ Before you commit your docs, it's a good idea to run the spelling checker. You'll need to install :pypi:`sphinxcontrib-spelling` first. Then from the @@ -180,7 +199,7 @@ one of the following: .. _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 diff --git a/docs/make.bat b/docs/make.bat index 72d71136c2..8376db57f0 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -189,20 +189,36 @@ results in %BUILDDIR%/doctest/output.txt. ) if "%1" == "spelling" ( - %SPHINXBUILD% -b spelling %ALLSPHINXOPTS% %BUILDDIR%/spelling - if errorlevel 1 exit /b 1 - echo. - echo.Check finished. Wrong words can be found in %BUILDDIR%/^ -spelling/output.txt. + call :run_spelling goto end ) if "%1" == "black" ( + call :run_black + goto end +) + +if "%1" == "check" ( + call :run_black + call :run_spelling + echo. + echo.All checks completed. + goto end +) + +:run_spelling + %SPHINXBUILD% -b spelling %ALLSPHINXOPTS% %BUILDDIR%/spelling + if errorlevel 1 exit /b 1 + echo. + echo.Check finished. Wrong words can be found in %BUILDDIR%/spelling/output.txt. + exit /b + +:run_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 -) + exit /b :end