mirror of
https://github.com/django/django.git
synced 2025-10-24 06:06:09 +00:00
Fixed #36485 -- Added lint-docs check in Tox and GitHub Actions.
The `check` docs target now runs spelling, black, and lint, so all current documentation quality checks can be run with a single command. Also documented the lint-docs check's availability and usage.
This commit is contained in:
@@ -69,11 +69,11 @@ command from any place in the Django source tree:
|
||||
$ tox
|
||||
|
||||
By default, ``tox`` runs the test suite with the bundled test settings file for
|
||||
SQLite, ``black``, ``blacken-docs``, ``flake8``, ``isort``, and the
|
||||
documentation spelling checker. In addition to the system dependencies noted
|
||||
elsewhere in this documentation, the command ``python3`` must be on your path
|
||||
and linked to the appropriate version of Python. A list of default environments
|
||||
can be seen as follows:
|
||||
SQLite, ``black``, ``blacken-docs``, ``flake8``, ``isort``, ``lint-docs`` and
|
||||
the documentation spelling checker. In addition to the system dependencies
|
||||
noted elsewhere in this documentation, the command ``python3`` must be on your
|
||||
path and linked to the appropriate version of Python. A list of default
|
||||
environments can be seen as follows:
|
||||
|
||||
.. console::
|
||||
|
||||
@@ -84,6 +84,7 @@ can be seen as follows:
|
||||
flake8>=3.7.0
|
||||
docs
|
||||
isort>=5.1.0
|
||||
lint-docs
|
||||
|
||||
Testing other Python versions and database backends
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
@@ -158,8 +158,9 @@ 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>`.
|
||||
:ref:`spelling <documentation-spelling-check>`,
|
||||
:ref:`code block formatting <documentation-code-block-format-check>`, and
|
||||
:ref:`documentation style <documentation-lint-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:
|
||||
@@ -215,6 +216,31 @@ installed, run the following command from the ``docs`` directory:
|
||||
The formatter will report any issues by printing them to the terminal and will
|
||||
reformat code blocks where possible.
|
||||
|
||||
.. _documentation-lint-check:
|
||||
|
||||
Documentation lint check
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Django's documentation is checked for reStructuredText style and formal issues
|
||||
using :pypi:`sphinx-lint`. This helps catch problems like stray tabs, trailing
|
||||
whitespace, excessive line length, and similar formatting problems.
|
||||
|
||||
Once ``sphinx-lint`` is installed, the check can be run with the following
|
||||
command from the ``docs`` directory:
|
||||
|
||||
.. console::
|
||||
|
||||
$ make lint
|
||||
|
||||
The command prints any violations to the terminal in the form
|
||||
``path:line: message``. If problems are encountered:
|
||||
|
||||
* Read the message and fix the indicated issue (for example, remove trailing
|
||||
whitespace, adjust backticks, or replace tabs with spaces).
|
||||
* For long lines consider wrapping text onto new lines or breaking long inline
|
||||
links into named references. The custom line length check should already skip
|
||||
common false positives such as headings, tables and long links.
|
||||
|
||||
.. _documentation-link-check:
|
||||
|
||||
Link check
|
||||
|
||||
Reference in New Issue
Block a user