I am also supportive but in my past (but worked ~2 years ago on this) no
checker was really "good" and I had massive false-positives. Hope the
static checkers have improved as early feedback can be helpful before CI
runs for long and fails. Unfortunately the static check seems not to be
easy.
On 02.05.26 17:22, Jarek Potiuk wrote:
Hi Yunhui,
Please proceed with the PR. I agree with Shahar that documentation files
should likely be excluded initially, as Sphinx verifies them and they use
extensions that might trigger false positives in basic checkers.
However, if you find a tool that can run on the docs/ folder without
excessive noise or easily fixable failures - as Piyush mentioned, it would
be a valuable addition. Flagging issues like missing empty lines before
lists locally via pre-commit would be better than waiting for CI results.
It may be difficult to keep it noise-free, but it is worth investigating.
Thanks,
Jarek Potiuk
On Sat, May 2, 2026 at 2:47 PM Piyush Mudgal <[email protected]>
wrote:
I support this proposal. Adding an RST linter to pre-commit hooks will help
contributors ensure documentation is correctly formatted before submission.
Best,
Piyush Mudgal
On Sat, May 2, 2026 at 4:34 PM Shahar Epstein <[email protected]> wrote:
I support this idea, as long as it targets RST files intended for
GitHub reading (mostly development-facing docs). Automatically
generated RST files should be excluded to avoid noisy failures and
keep the hook focused on files contributors edit directly. Later, we
could use such a linter to improve the templates used to generate
those files, but that requires some more research and can wait for a
later stage.
Shahar
On Sat, May 2, 2026 at 1:17 PM gui <[email protected]> wrote:
Hi everyone,
I'd like to propose adding an RST linter to our pre-commit hooks.
## Motivation
Recently, PR #66252 [1] was submitted to fix an RST heading level error
that broke GitHub rendering. Currently, such syntax errors are only
caught
during the documentation build process, which delays feedback for
contributors. By adding an RST linter, we can catch these issues
locally
before the code is even pushed.
## Current State
We have `rst-backticks` hook but no RST syntax validation.
## Proposal
Add either `rstcheck` [2] or `sphinx-lint` [3] to pre-commit:
```yaml
# rstcheck
- repo: https://github.com/rstcheck/rstcheck
rev: v6.2.5
hooks:
- id: rstcheck
additional_dependencies: ['rstcheck[sphinx,toml]']
```
Both tools catch RST syntax errors early. `rstcheck` is more
comprehensive;
`sphinx-lint` is lighter and Sphinx-focused.
## Note
Pre-commit hooks only run on changed files by default, so existing
documentation won't break. We can incrementally fix existing issues
over
time rather than in one big bang.
If there's interest, I can prepare a PR with the implementation.
Best regards,
Yunhui Chae
[1] https://github.com/apache/airflow/pull/66252
[2] https://github.com/rstcheck/rstcheck
[3] https://github.com/sphinx-contrib/sphinx-lint
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
