[llvm-dev] Linting rst files

[MyDeveloper Day via llvm-dev]

All

I've recently been doing some work in the clang-tidy module,
https://reviews.llvm.org/D55523

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/validate_check.py --no-maximize --rst
{} \; | grep warning | wc -l

14172

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

MyDeveloperDay
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20181214/09d37ac3/attachment.html>