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

[Gábor Horváth via cfe-dev]

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

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?
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> 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/.
> 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 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
>
> 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
>
> So a similar listing page is created:
> 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
>
>
> 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/
> .
>
> I wonder what you guys think about this approach?
>
> Thanks,
> Daniel
> _______________________________________________
> 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/d3b48c3d/attachment.html>