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] > > > > >
