mirror of
https://github.com/django/django.git
synced 2025-08-20 16:59:12 +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:
parent
cba7328196
commit
7f9bf357fe
@ -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."
|
||||
|
@ -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 <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:
|
||||
|
||||
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
|
||||
|
@ -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
|
||||
|
Loading…
x
Reference in New Issue
Block a user