[Django] #36485: Add linting tool for documentation

[Django]

#36485: Add linting tool for documentation
-------------------------------------+-------------------------------------
Reporter: David | Owner: David Smith
Smith |
Type: | Status: assigned
Cleanup/optimization |
Component: | Version: 5.2
Documentation |
Severity: Normal | Keywords:
Triage Stage: | Has patch: 0
Unreviewed |
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
-------------------------------------+-------------------------------------
As Natalia wrote on this [https://forum.djangoproject.com/t/automatic-
docs-linter-for-style-consistency/41383 forum post]

> Currently, style guidelines for docs are well documented, but checking
them is still a manual part of the review process. That often results in
extra back-and-forth over small formatting details, which can slow things
down. Automating this would help ease that overhead, making reviews more
efficient for both contributors and maintainers.

The documentation can be linted with [https://github.com/sphinx-contrib
/sphinx-lint?rgh-link-date=2025-06-09T22%3A42%3A19Z sphinx-lint] with some
modifications such that it works with Django's documentation. Main edits
are for Django's `.txt` extension (vs default `.rst`) and some additional
exceptions for the line length check.
--
Ticket URL: <https://code.djangoproject.com/ticket/36485>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#36485: Add linting tool for documentation
-------------------------------------+-------------------------------------

Reporter: David Smith | Owner: David
Type: | Smith
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 5.2
Severity: Normal | Resolution:
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by David Smith):

[PR https://github.com/django/django/pull/19549]
--
Ticket URL: <https://code.djangoproject.com/ticket/36485#comment:1>

[Django]

#36485: Add linting tool for documentation
-------------------------------------+-------------------------------------
Reporter: David Smith | Owner: David
Type: | Smith
Cleanup/optimization | Status: assigned

Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Natalia Bidart):

* has_patch: 0 => 1
* stage: Unreviewed => Accepted
* version: 5.2 => dev

Comment:

Thank you David! I'm so looking forward to this :-)
--
Ticket URL: <https://code.djangoproject.com/ticket/36485#comment:2>

[Django]

#36485: Add linting tool for documentation
-------------------------------------+-------------------------------------
Reporter: David Smith | Owner: David
Type: | Smith
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by nessita <124304+nessita@…>):

In [changeset:"7f9bf357feac06bb34017e1f6c7a7730b1991ede" 7f9bf35]:
{{{#!CommitTicketReference repository=""
revision="7f9bf357feac06bb34017e1f6c7a7730b1991ede"
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.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/36485#comment:3>

[Django]

#36485: Add linting tool for documentation
-------------------------------------+-------------------------------------
Reporter: David Smith | Owner: David
Type: | Smith
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Natalia <124304+nessita@…>):

In [changeset:"a9c7d4b703759e9903dd92899dd8ac662007baf3" a9c7d4b7]:
{{{#!CommitTicketReference repository=""
revision="a9c7d4b703759e9903dd92899dd8ac662007baf3"
[5.2.x] 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.

Backport of 7f9bf357feac06bb34017e1f6c7a7730b1991ede from main.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/36485#comment:4>

[Django]

#36485: Add linting tool for documentation
-------------------------------------+-------------------------------------
Reporter: David Smith | Owner: David
Type: | Smith
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Adam Johnson):

* cc: Adam Johnson (added)

--
Ticket URL: <https://code.djangoproject.com/ticket/36485#comment:5>

[Django]

#36485: Add linting tool for documentation
-------------------------------------+-------------------------------------
Reporter: David Smith | Owner: David
Type: | Smith
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:

Keywords: | Triage Stage: Ready for
| checkin

Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Natalia Bidart):

* stage: Accepted => Ready for checkin

--
Ticket URL: <https://code.djangoproject.com/ticket/36485#comment:6>

[Django]

#36485: Add linting tool for documentation
-------------------------------------+-------------------------------------
Reporter: David Smith | Owner: David
Type: | Smith
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by nessita <124304+nessita@…>):

In [changeset:"724e5ec6f2c89cacbd7c28e0e3ee63d292810cbd" 724e5ec6]:
{{{#!CommitTicketReference repository=""
revision="724e5ec6f2c89cacbd7c28e0e3ee63d292810cbd"
Refs #36485 -- Fixed dangling hyphen and unbalanced inline markup in docs.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/36485#comment:9>

[Django]

#36485: Add linting tool for documentation
-------------------------------------+-------------------------------------
Reporter: David Smith | Owner: David
Type: | Smith
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by nessita <124304+nessita@…>):

In [changeset:"6f8e23d1c10c7ce32cea82b65ad2af640015f147" 6f8e23d1]:
{{{#!CommitTicketReference repository=""
revision="6f8e23d1c10c7ce32cea82b65ad2af640015f147"
Refs #36485 -- Removed unnecessary parentheses in :meth: and :func: roles
in docs.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/36485#comment:8>

[Django]

#36485: Add linting tool for documentation
-------------------------------------+-------------------------------------
Reporter: David Smith | Owner: David
Type: | Smith
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by nessita <124304+nessita@…>):

In [changeset:"f81e6e3a53ee36e3f730a71aa55a5744982dd016" f81e6e3]:
{{{#!CommitTicketReference repository=""
revision="f81e6e3a53ee36e3f730a71aa55a5744982dd016"
Refs #36485 -- Rewrapped docs to 79 columns line length.

Lines in the docs files were manually adjusted to conform to the
79 columns limit per line (plus newline), improving readability and
consistency across the content.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/36485#comment:12>

[Django]

#36485: Add linting tool for documentation
-------------------------------------+-------------------------------------
Reporter: David Smith | Owner: David
Type: | Smith
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by nessita <124304+nessita@…>):

In [changeset:"4286a23df64f6ce3b9b6ed097f4d1aac7d9e0de4" 4286a23d]:
{{{#!CommitTicketReference repository=""
revision="4286a23df64f6ce3b9b6ed097f4d1aac7d9e0de4"
Refs #36485 -- Removed double spaces after periods in sentences.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/36485#comment:11>

[Django]

#36485: Add linting tool for documentation
-------------------------------------+-------------------------------------
Reporter: David Smith | Owner: David
Type: | Smith

Cleanup/optimization | Status: closed
Component: Documentation | Version: dev
Severity: Normal | Resolution: fixed

Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by nessita <124304+nessita@…>):

* resolution: => fixed
* status: assigned => closed

Comment:

In [changeset:"43e4d0a1422d87cc804097f7eb127b6ffa07e840" 43e4d0a]:
{{{#!CommitTicketReference repository=""
revision="43e4d0a1422d87cc804097f7eb127b6ffa07e840"
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.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/36485#comment:13>

[Django]

#36485: Add linting tool for documentation
-------------------------------------+-------------------------------------
Reporter: David Smith | Owner: David
Type: | Smith

Cleanup/optimization | Status: assigned

Component: Documentation | Version: dev
Severity: Normal | Resolution:

Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by nessita <124304+nessita@…>):

In [changeset:"01a460f23e470555a733b8980401402b7947bb9f" 01a460f2]:
{{{#!CommitTicketReference repository=""
revision="01a460f23e470555a733b8980401402b7947bb9f"
Refs #36485 -- Removed trailing spaces and tabs in docs.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/36485#comment:10>

[Django]

#36485: Add linting tool for documentation
-------------------------------------+-------------------------------------
Reporter: David Smith | Owner: David
Type: | Smith
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by nessita <124304+nessita@…>):

In [changeset:"ef2f16bc4824ca2b10b7f2845baf4d313c9c0da1" ef2f16b]:
{{{#!CommitTicketReference repository=""
revision="ef2f16bc4824ca2b10b7f2845baf4d313c9c0da1"
Refs #36485 -- Added sphinx-lint support and make lint rule for docs.

This adds a `lint.py` script to run sphinx-lint on Django's docs files,
a mathing `lint` target in the `docs/Makefile` and `docs/make.bat`, and
updates `docs/requirements.txt` accordingly.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/36485#comment:7>

[Django]

#36485: Add linting tool for documentation
-------------------------------------+-------------------------------------
Reporter: David Smith | Owner: David
Type: | Smith

Cleanup/optimization | Status: closed
Component: Documentation | Version: dev
Severity: Normal | Resolution: fixed

Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by nessita <124304+nessita@…>):

In [changeset:"9efce80ca7daccbcf315a81b250f5dc8b6d453a1" 9efce80]:
{{{#!CommitTicketReference repository=""
revision="9efce80ca7daccbcf315a81b250f5dc8b6d453a1"
Refs #36485 -- Ignored line-length formatting changes in git blame.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/36485#comment:14>

[Django]

#36485: Add linting tool for documentation
-------------------------------------+-------------------------------------
Reporter: David Smith | Owner: David
Type: | Smith
Cleanup/optimization | Status: closed
Component: Documentation | Version: dev
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by GitHub <noreply@…>):

In [changeset:"a627194567b3af2ef74bd89e404868932ff755b3" a6271945]:
{{{#!CommitTicketReference repository=""
revision="a627194567b3af2ef74bd89e404868932ff755b3"
Refs #36485 -- Corrected docs linter to detect too-long lines at file end.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/36485#comment:15>