This is an archive of the discontinued LLVM Phabricator instance.

[analyzer] Creating standard Sphinx documentation
ClosedPublic

Authored by dkrupp on Nov 12 2018, 8:05 AM.

Details

Summary

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:

If you agree with the direction I can transform the rest of the https://clang-analyzer.llvm.org/ documentation into rst.

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...

Diff Detail

Repository
rC Clang

Event Timeline

dkrupp created this revision.Nov 12 2018, 8:05 AM

I'll read through this as soon as possible, but a HUGE thank you for this. This is what the Static Analyzer desperately needed for years. This will trivialize documenting, so conversations about the inner workings of the analyzer will not be buried in many year old closed revisions.

@xazax.hun maybe your patch should be implemented with Sphinx too?

Please reupload with full context (-U99999).

Szelethus retitled this revision from Creating standard shpinx documentation for Clang Static Analyzer to [analyzer] Creating standard shpinx documentation.Nov 12 2018, 8:10 AM
dkrupp updated this revision to Diff 173679.Nov 12 2018, 8:15 AM

making the diff full context.

I do like the idea of moving the Clang Static Analyzer documentation to where the rest of the tools are documented. I believe the original reason the analyzer had a separate homepage is due to it was off by default in clang at the beginning and users downloaded it from the separate page.

I do see the value in having a consistent style across the tools and I do hope that we will end up editing rst files more often (as probably most of the analyzers devs do not really like HTML).

george.karpenkov retitled this revision from [analyzer] Creating standard shpinx documentation to [analyzer] Creating standard Sphinx documentation.Nov 12 2018, 11:15 AM

From a first glance, it's missing screenshots and an introduction section.

What do you propose we should do with other pages on the existing website? (OpenProjects / etc.)

What do you propose we should do with other pages on the existing website? (OpenProjects / etc.)

I think we should just move everything here, and forget about the old site, as there clearly isn't a desire to maintain it any longer.

NoQ added a subscriber: dcoughlin.

I think we should escalate this to cfe-dev first; this sounds pretty important.

@dcoughlin should definitely say a word here, as the code owner.

I agree that pictures and screenshots are very important to keep somehow. A terrifying amount of users think that the right way to use Static Analyzer is to read raw warnings without path notes in the command line.

dkrupp updated this revision to Diff 173846.Nov 13 2018, 7:16 AM

-scanbuild and xcode pictures are included now
-intro text ("What is Static Analysis?" etc.) are put under the Introduction section
-Download section is created, but I am not sure how well was the this Mac OSX binary release section was maintained. Should users really download from this site or through a package manager instead?

I will transform all the subpages after we come to an agreement that this is the way to go. For now, there are links to the old sub-pages from the main page.

@dcoughlin what do you think?

This is the current status.
Done:
Main: https://clang-analyzer.llvm.org/
Main/User manual/available checks: https://clang-analyzer.llvm.org/available_checks.html
Main/Mailing Lists

Not done:
Main/Filing Bugs: https://clang-analyzer.llvm.org/filing_bugs.html
Main/User manual/Obtaining the analyzer: https://clang-analyzer.llvm.org/installation.html
Main/User manual/Command line usage: https://clang-analyzer.llvm.org/scan-build.html
Main/User manual/Using within XCode: https://clang-analyzer.llvm.org/xcode.html
Main/Development/Checker Developer Manual: https://clang-analyzer.llvm.org/checker_dev_manual.html
Main/Development/Open Projects: https://clang-analyzer.llvm.org/open_projects.html
Main/Development/Potential Future Checkers: https://clang-analyzer.llvm.org/potential_checkers.html
Main/User manual/Source level annotations: https://clang-analyzer.llvm.org/annotations.html
Main/User manual/FAQ: https://clang-analyzer.llvm.org/faq.html

@dcoughlin could you please look into this?

MTC added a subscriber: MTC.Dec 3 2018, 10:53 PM
NoQ added a comment.Dec 12 2018, 10:07 PM

I poked Devin offline. It kinda seems to both of us that Sphinx is great for documentation that is updated regularly, but our fancy front page should probably stay. Similarly to how we still have the llvm.org front page, despite all the documentation. It's kinda atmospheric and friendly and people like it and/or are used to it.

Pretty much all other pages will look great in Sphinx. Everything under "User Manual" would indeed look like a manual, everything under "Development" would look more technical and trustworthy, the "Filing Bugs" page is pretty weird and unfriendly and should probably be reworked or removed anyway, the "Obtaining..." page is pretty much outdated and contains no useful info apart from "If you want the latest Analyzer, compile Clang from source and add it to your PATH". I'm a bit unsure about the FAQ page, it kinda feels like it should be as close to the front page and visible on the front page as possible, in order to inspire people to actually read it. We should give it more visibility, not hide it within the manual.

That I think sounds great! Thanks!

dkrupp updated this revision to Diff 180221.EditedJan 4 2019, 4:53 AM
dkrupp edited the summary of this revision. (Show Details)

Thanks @NoQ .
So I created a very simple main page with the table of contents only http://cc.elte.hu/clang-docs/docs/html/ClangStaticAnalyzer.html

The main contribution is that I created checkers.rst (see rendered at http://cc.elte.hu/clang-docs/docs/html/analyzer/checkers.html )
page which contains everything from available_checks.html and the alpha_checks.html pages.

If this patch is accepted then I will update the User Manual/Avaliable Chekcs link in the old homepage to point to this new checker page.

I found some old design documentation in clang/docs repository: DebugChecks.rst InitializerLists.rst IPA.rst nullability.rst RegionStore.rst I fixed some formatting syntax in them and linked them in from the main page under developer-docs section.

After this patch is accepted I plan to continue to transform the rest of the documents (SourceLevelAnnotions, Checker Developer Manual etc.)

serge-sans-paille resigned from this revision.Jan 7 2019, 1:52 AM

Cheers, this is as good as it gets! IRL we also mentioned making a unipage for each checker which would be awesome (and would require a lot of tedious work), but as a start, I'd much prefer browsing through this doc than the current one. Very much appreciated!

I won't formally accept this to make it stand out a little more.

docs/analyzer/checkers.rst
2004

While I would argue very strongly against the current website's every effort at hiding implicit checkers, when we deliberately call this site a documentation site, I definitely think that we should most include them here.

Although, don't sweat it too much just yet, while the structure is still being decided upon.

NoQ accepted this revision.Jan 31 2019, 12:32 PM

I think let's get this up and running and slowly redirect links from the front page to the new docs until only the front page is left?

docs/analyzer/checkers.rst
37–38

Wow, that's pretty cool. Can we actually merge documentation with regression tests somehow, so that to automatically ensure that the documentation is correct?

2004

Well, i mean, it's a good idea to make a distinction between a user guide from a developer guide. We should totally document these checkers, but we want to keep the user part of the guide user-comprehendable and, ideally, as short as possible. It's like people don't usually combine code comments with man pages; both are "documentation", but there's a huge difference between them driven by different target audience.

At the same time, we already have a better "Debug Checks" page.

This revision is now accepted and ready to land.Jan 31 2019, 12:32 PM
NoQ added a comment.Jan 31 2019, 2:11 PM

P.S. I also support the idea to have a separate page per checker. It encourages people to write as much documentation as necessary and continously expand it. Otherwise there's a perception that all docs need to be roughly of the same size and shape in order to make the page look consistent and not too cluttered.

Szelethus accepted this revision.Feb 4 2019, 5:08 AM

I'll do the honors. Thanks!

This revision was automatically updated to reflect the committed changes.

I'm getting a single buildbot failure, but I'm a little unsure how to fix it. Could you help?

http://lab.llvm.org:8011/builders/clang-sphinx-docs/builds/36985

24.610 [1/1/1] Generating html Sphinx documentation for clang into "/home/buildbot/llvm-build-dir/clang-sphinx-docs/llvm/build/tools/clang/docs/html"
FAILED: tools/clang/docs/CMakeFiles/docs-clang-html 
cd /home/buildbot/llvm-build-dir/clang-sphinx-docs/llvm/build/tools/clang/docs && /usr/bin/sphinx-build -b html -d /home/buildbot/llvm-build-dir/clang-sphinx-docs/llvm/build/tools/clang/docs/_doctrees-clang-html -q -W /home/buildbot/llvm-build-dir/clang-sphinx-docs/llvm/src/tools/clang/docs /home/buildbot/llvm-build-dir/clang-sphinx-docs/llvm/build/tools/clang/docs/html

Warning, treated as error:
/home/buildbot/llvm-build-dir/clang-sphinx-docs/llvm/src/tools/clang/docs/analyzer/checkers.rst:1945: WARNING: unknown document: DebugChecks
NoQ added a comment.Feb 4 2019, 5:35 PM

Dunno but made a random guess in the inline comment.

docs/analyzer/checkers.rst
1946

The error is on this line. It might be that this link should mention the directory (something like developer-docs/DebugChecks). Previously DebugChecks was on the top level, so it wasn't necessary.

Szelethus added inline comments.Feb 5 2019, 2:20 AM
docs/analyzer/checkers.rst
1946

Yup, thanks!