1
0
mirror of https://github.com/django/django.git synced 2025-08-21 01:09:13 +00:00

Refs #36485 -- Grouped docs checks under a unified make check target.

Added a new 'check' rule to the docs Makefile which runs both the black
and spelling checks.
This commit is contained in:
David Smith 2025-06-25 21:40:07 +01:00 committed by nessita
parent cba7328196
commit 7f9bf357fe
3 changed files with 47 additions and 8 deletions

View File

@ -174,3 +174,7 @@ black:
| xargs blacken-docs --rst-literal-block; echo $$? > "$(BUILDDIR)/black/output.txt" | xargs blacken-docs --rst-literal-block; echo $$? > "$(BUILDDIR)/black/output.txt"
@echo @echo
@echo "Code blocks reformatted" @echo "Code blocks reformatted"
check: spelling black
@echo
@echo "Style and spelling checks completed."

View File

@ -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 :source:`docs/internals/contributing/writing-documentation.txt` and rebuild the
HTML with ``make html``. HTML with ``make html``.
.. _documentation-checks:
Documentation quality checks
----------------------------
Several checks help maintain Django's documentation quality, including
:ref:`spelling <documentation-spelling-check>` and
:ref:`code block formatting <documentation-code-block-format-check>`.
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: .. _documentation-spelling-check:
Spelling check Spelling check
-------------- ~~~~~~~~~~~~~~
Before you commit your docs, it's a good idea to run the spelling checker. 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 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: .. _documentation-code-block-format-check:
Code block format check Code block format check
----------------------- ~~~~~~~~~~~~~~~~~~~~~~~
All Python code blocks should be formatted using the :pypi:`blacken-docs` All Python code blocks should be formatted using the :pypi:`blacken-docs`
auto-formatter. This is automatically run by the :ref:`pre-commit hook auto-formatter. This is automatically run by the :ref:`pre-commit hook

View File

@ -189,20 +189,36 @@ results in %BUILDDIR%/doctest/output.txt.
) )
if "%1" == "spelling" ( if "%1" == "spelling" (
%SPHINXBUILD% -b spelling %ALLSPHINXOPTS% %BUILDDIR%/spelling call :run_spelling
if errorlevel 1 exit /b 1
echo.
echo.Check finished. Wrong words can be found in %BUILDDIR%/^
spelling/output.txt.
goto end goto end
) )
if "%1" == "black" ( 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 ( for /f "usebackq tokens=*" %%i in (`dir *.txt /s /b ^| findstr /v /c:"_build" /c:"_theme"`) do (
blacken-docs --rst-literal-block %%i blacken-docs --rst-literal-block %%i
) )
echo. echo.
echo.Code blocks reformatted echo.Code blocks reformatted
) exit /b
:end :end