From 43e4d0a1422d87cc804097f7eb127b6ffa07e840 Mon Sep 17 00:00:00 2001 From: David Smith Date: Mon, 2 Jun 2025 08:22:08 +0100 Subject: 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. --- .../contributing/writing-code/unit-tests.txt | 11 ++++---- .../contributing/writing-documentation.txt | 30 ++++++++++++++++++++-- 2 files changed, 34 insertions(+), 7 deletions(-) (limited to 'docs/internals') diff --git a/docs/internals/contributing/writing-code/unit-tests.txt b/docs/internals/contributing/writing-code/unit-tests.txt index 05b2bf09c6..b4bc429af5 100644 --- a/docs/internals/contributing/writing-code/unit-tests.txt +++ b/docs/internals/contributing/writing-code/unit-tests.txt @@ -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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/internals/contributing/writing-documentation.txt b/docs/internals/contributing/writing-documentation.txt index ff9bf5da47..42e8aa7a89 100644 --- a/docs/internals/contributing/writing-documentation.txt +++ b/docs/internals/contributing/writing-documentation.txt @@ -158,8 +158,9 @@ Documentation quality checks ---------------------------- Several checks help maintain Django's documentation quality, including -:ref:`spelling ` and -:ref:`code block formatting `. +:ref:`spelling `, +:ref:`code block formatting `, and +:ref:`documentation style `. 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 -- cgit v1.3