Yep, like the longer idea. But not so much for the reminder thing. Will most likely be ignored.
Best, Wei On Sat, May 9, 2026 at 9:36 AM gui <[email protected]> wrote: > Thank you all for the feedback! > I understand the concern about adding more noise, and I agree that the > current docs build CI provides sufficient feedback. > I won't pursue the CI workflow approach. > > 2026년 5월 9일 (토) 오전 6:23, Vincent Beck <[email protected]>님이 작성: > > > Very much agree. I am quite against adding a new workflow and will yet > add > > more noise, more message to read. The rather keep the CI as is. > > > > On 2026/05/08 21:18:00 Jarek Potiuk wrote: > > > 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] > > > >> > > > > >> > > > > >> > > > > > > > > > > > --------------------------------------------------------------------- > > To unsubscribe, e-mail: [email protected] > > For additional commands, e-mail: [email protected] > > > > >
