Linting rst files


I’ve recently been doing some work in the clang-tidy module,

I had noticed that a lot of code review comments in that area came about because of inconsistent style in the .rst documentation

I wrote a small python script to check the documentation for simple errors like

  • double blank lines
  • double spaces
  • empty last lines
  • trailing spaces
  • inconsistent markup and headers above

It was only later that I noticed these problems were actually universal across all of LLVM, both in llvm/docs and llvm/tools/clang/docs and not just in llvm/tools/clang/tools/extra/docs

Its definitely not a full sphinx parser so I’m sure it would go wrong from time to time, but globally in llvm it found 1000s of minor errors in rst files all across the llvm tree

$ find . -name ‘*.rst’ -exec ./tools/clang/tools/extra/clang-tidy/ --no-maximize --rst {} ; | grep warning | wc -l


Gave 14,000+ warnings across the entire LLVM tree

6231 - line is in excess of 80 characters

4774 - line contains double spaces

1528 - line multiple blank lines

1078 - line trailing whitespace

484 - title and markup non matching lengths

81 - empty lines at the end of the file (almost 16% of all .rst files)

I think those doing code reviews over in clang-tidy would like developers of new checkers to check their rst files as part of the build process, and for those sorts of warning to be “on them” at build time and not on the reviewer

As I’ve looked at this more holistically I see value in something simpler for all of llvm,

  1. is this something people care about?
  2. are code review comments regarding the state of the rst files common in other areas?
  3. where would such a tool go (llvm/lnt hasn’t had a commit since 2009)?
  4. how would we (if at all) bring such warnings into the build system, if desired?

Is there someone I should speak to regarding the wider llvm tooling? (I couldn’t find anything in CODE_OWNERS.txt that would point me to who owns that.)

I realize changing a few .rst files isn’t pushing the envelop of LLVM/clang, but perhaps for those of us without the skills yet to dive in and write a new backend, its something we can contribute to.

Comments and any Feedback are welcome