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]
