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