mirror of
https://github.com/django/django.git
synced 2024-12-22 09:05:43 +00:00
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 <smithdc@gmail.com>
This commit is contained in:
parent
9cf2a5df70
commit
6015bab80e
21
.github/workflows/docs.yml
vendored
21
.github/workflows/docs.yml
vendored
@ -38,3 +38,24 @@ jobs:
|
|||||||
run: |
|
run: |
|
||||||
cd docs
|
cd docs
|
||||||
sphinx-build -b spelling -n -q -W --keep-going -d _build/doctrees -D language=en_US -j auto . _build/spelling
|
sphinx-build -b spelling -n -q -W --keep-going -d _build/doctrees -D language=en_US -j auto . _build/spelling
|
||||||
|
|
||||||
|
blacken-docs:
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
name: blacken-docs
|
||||||
|
steps:
|
||||||
|
- name: Checkout
|
||||||
|
uses: actions/checkout@v3
|
||||||
|
- name: Set up Python
|
||||||
|
uses: actions/setup-python@v4
|
||||||
|
with:
|
||||||
|
python-version: '3.11'
|
||||||
|
- run: python -m pip install blacken-docs
|
||||||
|
- name: Build docs
|
||||||
|
run: |
|
||||||
|
cd docs
|
||||||
|
make black
|
||||||
|
RESULT=`cat _build/black/output.txt`
|
||||||
|
if [ "$RESULT" -gt 0 ]; then
|
||||||
|
echo "💥 📢 Code blocks in documentation must be reformatted with blacken-docs 📢 💥"
|
||||||
|
fi;
|
||||||
|
exit $RESULT
|
||||||
|
@ -4,6 +4,12 @@ repos:
|
|||||||
hooks:
|
hooks:
|
||||||
- id: black
|
- id: black
|
||||||
exclude: \.py-tpl$
|
exclude: \.py-tpl$
|
||||||
|
- repo: https://github.com/adamchainz/blacken-docs
|
||||||
|
rev: 1.13.0
|
||||||
|
hooks:
|
||||||
|
- id: blacken-docs
|
||||||
|
additional_dependencies:
|
||||||
|
- black==23.1.0
|
||||||
- repo: https://github.com/PyCQA/isort
|
- repo: https://github.com/PyCQA/isort
|
||||||
rev: 5.12.0
|
rev: 5.12.0
|
||||||
hooks:
|
hooks:
|
||||||
|
@ -49,6 +49,7 @@ help:
|
|||||||
@echo " linkcheck to check all external links for integrity"
|
@echo " linkcheck to check all external links for integrity"
|
||||||
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
|
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
|
||||||
@echo " spelling to check for typos in documentation"
|
@echo " spelling to check for typos in documentation"
|
||||||
|
@echo " black to apply the black formatting to code blocks in documentation"
|
||||||
|
|
||||||
|
|
||||||
clean:
|
clean:
|
||||||
@ -165,3 +166,10 @@ spelling:
|
|||||||
@echo
|
@echo
|
||||||
@echo "Check finished. Wrong words can be found in " \
|
@echo "Check finished. Wrong words can be found in " \
|
||||||
"$(BUILDDIR)/spelling/output.txt."
|
"$(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"
|
||||||
|
@ -291,9 +291,9 @@ All code changes
|
|||||||
|
|
||||||
* Does the :doc:`coding style
|
* Does the :doc:`coding style
|
||||||
</internals/contributing/writing-code/coding-style>` conform to our
|
</internals/contributing/writing-code/coding-style>` conform to our
|
||||||
guidelines? Are there any ``black``, ``flake8``, or ``isort`` errors? You
|
guidelines? Are there any ``black``, ``blacken-docs``, ``flake8``, or
|
||||||
can install the :ref:`pre-commit <coding-style-pre-commit>` hooks to
|
``isort`` errors? You can install the :ref:`pre-commit
|
||||||
automatically catch these errors.
|
<coding-style-pre-commit>` hooks to automatically catch these errors.
|
||||||
* If the change is backwards incompatible in any way, is there a note
|
* If the change is backwards incompatible in any way, is there a note
|
||||||
in the release notes (``docs/releases/A.B.txt``)?
|
in the release notes (``docs/releases/A.B.txt``)?
|
||||||
* Is Django's test suite passing?
|
* Is Django's test suite passing?
|
||||||
|
@ -69,17 +69,18 @@ command from any place in the Django source tree:
|
|||||||
$ tox
|
$ tox
|
||||||
|
|
||||||
By default, ``tox`` runs the test suite with the bundled test settings file for
|
By default, ``tox`` runs the test suite with the bundled test settings file for
|
||||||
SQLite, ``black``, ``flake8``, ``isort``, and the documentation spelling
|
SQLite, ``black``, ``blacken-docs``, ``flake8``, ``isort``, and the
|
||||||
checker. In addition to the system dependencies noted elsewhere in this
|
documentation spelling checker. In addition to the system dependencies noted
|
||||||
documentation, the command ``python3`` must be on your path and linked to the
|
elsewhere in this documentation, the command ``python3`` must be on your path
|
||||||
appropriate version of Python. A list of default environments can be seen as
|
and linked to the appropriate version of Python. A list of default environments
|
||||||
follows:
|
can be seen as follows:
|
||||||
|
|
||||||
.. console::
|
.. console::
|
||||||
|
|
||||||
$ tox -l
|
$ tox -l
|
||||||
py3
|
py3
|
||||||
black
|
black
|
||||||
|
blacken-docs
|
||||||
flake8>=3.7.0
|
flake8>=3.7.0
|
||||||
docs
|
docs
|
||||||
isort>=5.1.0
|
isort>=5.1.0
|
||||||
|
@ -211,6 +211,9 @@ documentation:
|
|||||||
"last bit" of that path. So ``:mod:`~django.contrib.auth``` will
|
"last bit" of that path. So ``:mod:`~django.contrib.auth``` will
|
||||||
display a link with the title "auth".
|
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'
|
* Use :mod:`~sphinx.ext.intersphinx` to reference Python's and Sphinx'
|
||||||
documentation.
|
documentation.
|
||||||
|
|
||||||
@ -258,6 +261,13 @@ documentation:
|
|||||||
also need to define a reference to the documentation for that environment
|
also need to define a reference to the documentation for that environment
|
||||||
variable using :rst:dir:`.. envvar:: <envvar>`.
|
variable using :rst:dir:`.. envvar:: <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
|
Django-specific markup
|
||||||
======================
|
======================
|
||||||
|
|
||||||
|
@ -35,6 +35,7 @@ if "%1" == "help" (
|
|||||||
echo. linkcheck to check all external links for integrity
|
echo. linkcheck to check all external links for integrity
|
||||||
echo. doctest to run all doctests embedded in the documentation if enabled
|
echo. doctest to run all doctests embedded in the documentation if enabled
|
||||||
echo. spelling to check for typos in documentation
|
echo. spelling to check for typos in documentation
|
||||||
|
echo. black to apply the black formatting to code blocks in documentation
|
||||||
goto end
|
goto end
|
||||||
)
|
)
|
||||||
|
|
||||||
@ -196,4 +197,12 @@ spelling/output.txt.
|
|||||||
goto end
|
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
|
:end
|
||||||
|
@ -1,3 +1,4 @@
|
|||||||
pyenchant
|
pyenchant
|
||||||
Sphinx>=4.5.0
|
Sphinx>=4.5.0
|
||||||
sphinxcontrib-spelling
|
sphinxcontrib-spelling
|
||||||
|
blacken-docs
|
||||||
|
11
tox.ini
11
tox.ini
@ -9,6 +9,7 @@ skipsdist = true
|
|||||||
envlist =
|
envlist =
|
||||||
py3
|
py3
|
||||||
black
|
black
|
||||||
|
blacken-docs
|
||||||
flake8
|
flake8
|
||||||
docs
|
docs
|
||||||
isort
|
isort
|
||||||
@ -39,6 +40,16 @@ deps = black
|
|||||||
changedir = {toxinidir}
|
changedir = {toxinidir}
|
||||||
commands = black --check --diff .
|
commands = black --check --diff .
|
||||||
|
|
||||||
|
[testenv:blacken-docs]
|
||||||
|
basepython = python3
|
||||||
|
usedevelop = false
|
||||||
|
allowlist_externals =
|
||||||
|
make
|
||||||
|
deps = blacken-docs
|
||||||
|
changedir = docs
|
||||||
|
commands =
|
||||||
|
make black
|
||||||
|
|
||||||
[testenv:flake8]
|
[testenv:flake8]
|
||||||
basepython = python3
|
basepython = python3
|
||||||
usedevelop = false
|
usedevelop = false
|
||||||
|
Loading…
Reference in New Issue
Block a user