[cfe-dev] [RFC] Tutorial for Clang Analyzer Plugins

[Sean Silva]

On Mon, Jan 7, 2013 at 1:36 PM, Jordan Rose <jordan_rose at apple.com> wrote:
> Hi, Sean. Anna and I discussed this a bit and we decided that what's in
> docs/analyzer/ really shouldn't appear on the analyzer website at all. It's
> internals documentation that is only relevant to people working on the
> static analyzer, and we don't yet know how we want to expose that on the
> site.

Ah, ok, so clang-analyzer.llvm.org is primarily a user-facing site,
rather than a site for developers "working on the static analyzer"; I
wasn't quite grokking that. That makes sense then, although then it
seems like <http://clang-analyzer.llvm.org/checker_dev_manual.html> is
misplaced (or maybe I misunderstand what "working on the static
analyzer" means).

> What does seem interesting is transitioning the entire analyzer site over to
> Sphinx, for increasing consistency among the LLVM projects. It's the pages
> people actually use that benefit most from transitioning to Sphinx, rather
> than random docs. Then there's no reason to have a docs/ subdirectory there,
> either.

This is certainly a possibility. One of the primary advantages of
Sphinx is simply making it easier to write content, and it is much
more suitable for a "website hosted in an SVN repo" than HTML.
However, see below.

> We were then wondering why the same isn't happening for LLVM and Clang (and
> LLDB?). Transitioning the docs is great, but it's very jarring to have half
> of each site in Sphinx and half in HTML…and all with different themes. I
> think we'd prefer that the analyzer site not transition to Sphinx at all
> unless we can do the entire site at once.

The stylistic consistency can be achieved in a fairly straightforward
way with appropriate CSS. The bottom line though is that we don't have
anybody who is responsible for making everything look and feel
consistent, so naturally it doesn't happen. What we really need is for
one of the many large companies invested in LLVM to step up and get
one of their web developers/designers to put some effort into the site
(my impression is that this is exactly how our awesome dragon logo
came to be). Since you work for one such large company, maybe you
could try to get the ball rolling on that? Feel free to put them in
contact with me if that would help in any way.

I fully agree though, the current pages are an incoherent mess from a
web design point of view: that's what happens when compiler and
toolchain writers try to do web design!

-- Sean Silva