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
