Sorry - sent to fast. We have enough of those reminders already ... When the docs will be built on CI and fail in your PR - you already have sufficient feedback your doc build fails - no additional workflow is needed.
On Fri, May 8, 2026 at 11:13 PM Jarek Potiuk <[email protected]> wrote: > 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] >> > >> > >> >
