I think prompts to check rendering are counter-productive. We do not want more messages or reminders. We have enough
On Fri, May 8, 2026 at 8:10 AM gui <[email protected]> wrote: > Hi everyone, > First of all, thank you all for sharing your thoughts and suggestions. > The discussion really helped me investigate the options more thoroughly. > > After testing both tools, I found some limitations: > 1. **rstcheck** has false positives in our codebase > 2. **sphinx-lint** didn't catch the heading level issue from PR #66252 > > Given these findings, I'd like to propose a lighter-weight alternative: > > Instead of adding a linter, we could add a GitHub CI workflow that posts > a reminder comment on PRs that modify `.rst` files, prompting the author > to check RST rendering on GitHub. > > This approach: > - Doesn't require fixing existing documentation issues > - Avoids false positives from linters > - Provides just-in-time reminders during code review > > If this direction isn't preferred, that's completely fine - I just wanted > to share what I found during the investigation. > I'd love to hear your thoughts on this alternative approach. > > Best regards, > Yunhui Chae > > 2026년 5월 3일 (일) 오전 12:57, Jens Scheffler <[email protected]>님이 작성: > > > 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] > > > > >
