[analyzer] migrate Clang Static Analyzer documentation to sphinx

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

[analyzer] migrate Clang Static Analyzer documentation to sphinx

Oleg Smolsky via cfe-dev

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
[hidden email]
http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev
Reply | Threaded
Open this post in threaded view
|

Re: [analyzer] migrate Clang Static Analyzer documentation to sphinx

Oleg Smolsky 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
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 <[hidden email]> 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
[hidden email]
http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev

_______________________________________________
cfe-dev mailing list
[hidden email]
http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev
Reply | Threaded
Open this post in threaded view
|

Re: [analyzer] migrate Clang Static Analyzer documentation to sphinx

Oleg Smolsky via cfe-dev


On Nov 30, 2018, at 2:10 AM, Gábor Horváth via cfe-dev <[hidden email]> 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
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 <[hidden email]> 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
[hidden email]
http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev
_______________________________________________
cfe-dev mailing list
[hidden email]
http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev


_______________________________________________
cfe-dev mailing list
[hidden email]
http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev