[analyzer] migrate Clang Static Analyzer documentation to sphinx

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 :wink:

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

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:

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

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:

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.