[PATCH] D54429: Creating standard shpinx documentation for Clang Static Analyzer

Daniel Krupp via Phabricator via cfe-commits cfe-commits at lists.llvm.org
Mon Nov 12 08:05:44 PST 2018


dkrupp created this revision.
dkrupp added reviewers: Szelethus, NoQ, george.karpenkov.
dkrupp added a project: clang.
Herald added subscribers: cfe-commits, donat.nagy, jfb, arphaman, a.sidorin, rnkovacs, baloghadamsoftware, whisperity.

Standard Clang tools (ThreadSanitizer, MemorySanitizer, DataFlowSanitizer etc.)
all have documentation delivered with Clang and build using Sphinx tool.
Would be great to have the ClangSA docs there too in sphinx markup.

I wonder what you guys think about this approach?

      

In this patch the analyzer's documentation main and checker pages are
transformed into Sphinx rst to be part of the standard clang documentation tree: https://clang.llvm.org/docs/

The generated new documentation would look like this:
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 ;)

In detail this patch contains the following contributions:

      

- Transformation of the main page https://clang-analyzer.llvm.org/ to http://cc.elte.hu/clang-docs/docs/html/ClangStaticAnalyzer.html
- Transformation of the https://clang-analyzer.llvm.org/available_checks.html and https://clang-analyzer.llvm.org/alpha_checks.html pages to http://cc.elte.hu/clang-docs/docs/html/analyzer/checkers.html
- Per checker page added for alpha.cplusplus.UninitializedObject checker. Would be great to create similar doc for all checkers in the long term. See http://cc.elte.hu/clang-docs/docs/html/analyzer/checkers/UninitializedObject.html
- Design discussion documents were renamed and formatted to rst and linked from the Development/Design Discussions section.

If you agree with the direction I can transform the rest of the https://clang-analyzer.llvm.org/ documentation into rst. But most importantly we would like to have a per checker one pager doc like the one in http://cc.elte.hu/clang-docs/docs/html/analyzer/checkers/UninitializedObject.html

RST seemed to be a better format than plain HTML. Then we could make mandatory for checker author to write such one pagers to their checkers similar to clang-tidy...


Repository:
  rC Clang

https://reviews.llvm.org/D54429

Files:
  docs/ClangStaticAnalyzer.rst
  docs/analyzer/DesignDiscussions/IPA.rst
  docs/analyzer/DesignDiscussions/InitializerLists.rst
  docs/analyzer/DesignDiscussions/RegionStore.rst
  docs/analyzer/DesignDiscussions/nullability.rst
  docs/analyzer/IPA.txt
  docs/analyzer/RegionStore.txt
  docs/analyzer/checkers.rst
  docs/analyzer/checkers/UninitializedObject.rst
  docs/analyzer/nullability.rst
  docs/conf.py
  docs/index.rst

-------------- next part --------------
A non-text attachment was scrubbed...
Name: D54429.173675.patch
Type: text/x-patch
Size: 94864 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20181112/38d075e2/attachment-0001.bin>


More information about the cfe-commits mailing list