diff options
| -rw-r--r-- | .github/workflows/docs.yml | 16 | ||||
| -rw-r--r-- | docs/Makefile | 2 | ||||
| -rw-r--r-- | docs/internals/contributing/writing-code/unit-tests.txt | 11 | ||||
| -rw-r--r-- | docs/internals/contributing/writing-documentation.txt | 30 | ||||
| -rw-r--r-- | docs/make.bat | 1 | ||||
| -rw-r--r-- | docs/spelling_wordlist | 1 | ||||
| -rw-r--r-- | tox.ini | 11 |
7 files changed, 64 insertions, 8 deletions
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index df183a5c42..d648e8b5fb 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -58,3 +58,19 @@ jobs: echo "💥 📢 Code blocks in documentation must be reformatted with blacken-docs 📢 💥" fi; exit $RESULT + + lint-docs: + runs-on: ubuntu-latest + name: lint-docs + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.13' + - run: python -m pip install sphinx-lint + - name: Build docs + run: | + cd docs + make lint diff --git a/docs/Makefile b/docs/Makefile index 78cbccd00e..3545332a40 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -181,6 +181,6 @@ lint: @echo @echo "Documentation lint complete." -check: spelling black +check: spelling black lint @echo @echo "Style and spelling checks completed." 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 <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 diff --git a/docs/make.bat b/docs/make.bat index 27e3c1143d..5c06278972 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -205,6 +205,7 @@ if "%1" == "lint" ( ) if "%1" == "check" ( + call :run_lint call :run_black call :run_spelling echo. diff --git a/docs/spelling_wordlist b/docs/spelling_wordlist index 0923fae08e..864b99f84a 100644 --- a/docs/spelling_wordlist +++ b/docs/spelling_wordlist @@ -39,6 +39,7 @@ backport backported backports backtick +backticks backtraces balancer basename @@ -13,6 +13,7 @@ envlist = flake8 docs isort + lint-docs # Add environment to use the default python3 installation [testenv:py3] @@ -87,3 +88,13 @@ allowlist_externals = commands = npm install npm test + +[testenv:lint-docs] +basepython = python3 +usedevelop = false +allowlist_externals = + make +deps = sphinx-lint +changedir = docs +commands = + make lint |