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:
parent
cba7328196
commit
7f9bf357fe
@ -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."
|
||||||
|
@ -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
|
||||||
|
@ -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
|
||||||
|
Loading…
x
Reference in New Issue
Block a user