[cfe-dev] [analyzer] migrate Clang Static Analyzer documentation to sphinx

[George Karpenkov via cfe-dev]

> On Nov 30, 2018, at 2:10 AM, Gábor Horváth via cfe-dev <cfe-dev at lists.llvm.org> wrote:
> 
> Hi!
> 
> I do see the value of having a consistent format across all clang project's documentation. But a more important aspect is to have better visibility.
> Right now we have analyzer related documentation:
> * In docs/analyzer folder
> * At the analyzer's homepage
> * lib/StaticAnalyzer/README.txt
> * The checker in 24 hour talk
> * We have https://github.com/haoNoQ/clang-analyzer-guide <https://github.com/haoNoQ/clang-analyzer-guide>
> 
> Having one updated place as a single source of truth would be a great QoL improvement which could make it easier to get started with the analyzer.
> I think the lack of such place is one of the biggest obstacles for newcomers.
> 
> Having a more consistent style of documentation with clang tidy for the individual checkers is also a plus from the user's point of view.
> The current per checker documentation at the analyzer's homepage is often lacking. They are great for getting an idea what a check is about but they do not cover all of the detected cases, do not cover configuration options and do not give the user any advice how to actually solve the problems and what is the best way to suppress potential false positives.
> 
> BTW, are there any users who rely on the analyzer distribution on the analyzer's homepage rather than the analyzer within a clang distribution?

I vaguely recall hearing that it comes from the days when the analyzer was not readily available within Clang.
Right now it’s severely out of date, and IMO should be removed.

> If we do not support that separate distribution I would rather remove it from the analyzer's homepage regardless of the decision of moving the site to the common format.
> 
> Regards,
> Gabor
>  
> 
> On Tue, 13 Nov 2018 at 16:50, Dániel Krupp via cfe-dev <cfe-dev at lists.llvm.org <mailto:cfe-dev at lists.llvm.org>> wrote:
> Dear Analyzer Community,
> 
>  
> 
> Most standard Clang tools (ThreadSanitizer, MemorySanitizer, DataFlowSanitizer etc.)
> have documentation delivered with Clang and build using Sphinx tool at  https://clang.llvm.org/docs/ <https://clang.llvm.org/docs/>.
> I thought it would be great to have the ClangSA docs there too in sphinx markup.
> 
> I created a patch https://reviews.llvm.org/D54429 <https://reviews.llvm.org/D54429> where analyzer's documentation main page and the checker sub-pages are
> transformed into Sphinx RST.
> 
> This is how it looks like now:
> 
> http://cc.elte.hu/clang-docs/docs/html/ClangStaticAnalyzer.html <http://cc.elte.hu/clang-docs/docs/html/ClangStaticAnalyzer.html>
> Advantages:
> 
> ·         The documentation is easier to be maintained in Sphinx markup compared to raw HTML
> 
> ·         The documentation is easier found in the standard clang doc tree
> 
> ·         The generated documentation looks nicer ;)
> 
> 
> What was also missing (for many users) is the documentation of the checkers. Similar to the one-pagers what we have for clang-tidy: http://clang.llvm.org/extra/clang-tidy/checks/list.html <http://clang.llvm.org/extra/clang-tidy/checks/list.html>
> 
> So a similar listing page is created: http://cc.elte.hu/clang-docs/docs/html/analyzer/checkers.html <http://cc.elte.hu/clang-docs/docs/html/analyzer/checkers.html>
> With a specific one-pager example: http://cc.elte.hu/clang-docs/docs/html/analyzer/checkers/UninitializedObject.html <http://cc.elte.hu/clang-docs/docs/html/analyzer/checkers/UninitializedObject.html>
> 
> In practice the pages can be migrated one by one (after sanitizing them) and at end a redirection can be set up at https://clang-analyzer.llvm.org/ <https://clang-analyzer.llvm.org/>.
> 
> I wonder what you guys think about this approach?
> 
> Thanks,
> Daniel
> 
> _______________________________________________
> cfe-dev mailing list
> cfe-dev at lists.llvm.org <mailto:cfe-dev at lists.llvm.org>
> http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev <http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev>
> _______________________________________________
> cfe-dev mailing list
> cfe-dev at lists.llvm.org
> http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20181130/0e85c36d/attachment.html>