aaron.ballman added a comment. In D64454#3130696 <https://reviews.llvm.org/D64454#3130696>, @whisperity wrote:
> In D64454#3124312 <https://reviews.llvm.org/D64454#3124312>, @aaron.ballman > wrote: > >> Yeah, I was worried this would get out of sycn and it really did not take >> long for that to happen in practice. I think there's utility in listing the >> checks in clang-tidy's documentation instead of pointing users to the SA >> documentation page. Users should have one website to go to where they can >> see what clang-tidy checks are available to them. > > Does this still apply given that the quality and formatting match of the > documentation website increased over the past one or two releases? The old > website <http://clang-analyzer.llvm.org/> if I see correctly no longer lists > the checkers (and the previous format was also increasingly outdated and bad > experience...), and we have the RST-based new website > <http://clang.llvm.org/docs/ClangStaticAnalyzer.html>. I think that clang-tidy users should be able to view the clang-tidy docs and see what checks are available to them (including static analyzer checks). Similarly, I think CSA users should be able to view the CSA docs and see what checks are available to them (including the clang-tidy checks that I think we're now exposing or were exploring exposing). > Come to think of it, maybe some RST hacks could automate "pulling in" the > list from the (new) CSA website to the Tidy list, as long as maybe they are > in a separate category (heading) in the Tidy list? > Although I'm unsure how much being `/tools/clang/` and > `/tools/clang/tools/extra/` mess this thing up. > In case of Python, for example, there is a well-understood way of registering > the documentation site of third-party packages, and //your// documentation > generator can automatically generate the cross-reference that links to the > other, from your doc's point-of-view, external website. But that involves a > considerable amount of "magic". > As far as I know, Sphinx is written in Python, so one could write Python code > that runs //during// the documentation generation (at least the RST part, I'm > not sure about the `man` or `infopages` or `groff` stuff!) that can do > "magic". That's a neat idea! So long as it doesn't become a maintenance burden for some reason, I think it could possibly be a viable path forward. > ---- > > What we //COULD// do, however, is get rid of the individual checker > documentation files (which all just contain machine generated redirects, at > least according to this diff...) and have ALL the cross-referencing links > (hand-written, autogenerated by our integration, or autogenerated by RST > magic) point to not a page living inside Tidy's scope that just does a > redirect, but to the appropriate heading in the (new) CSA doc suite? > > (Then again, irrespective of what magic we will use, the non-trivial grouping > structure on the new CSA docs site can become a problem...) If I understand correctly, that would then get rid of the concrete list of checks from `list.rst`, wouldn't it? Otherwise, we're still going to get out of date trivially as new CSA checks are added but people forget to update `list.rst`. (Or did I misunderstand?) Repository: rL LLVM CHANGES SINCE LAST ACTION https://reviews.llvm.org/D64454/new/ https://reviews.llvm.org/D64454 _______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
