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

[Daniel Dunbar]

On Mon, Jan 7, 2013 at 2:00 PM, Anna Zaks <ganna at apple.com> wrote:

>
> On Jan 7, 2013, at 12:50 PM, Daniel Dunbar <daniel at zuster.org> wrote:
>
> Ok, done.
>
> I just realized I didn't read Jordan's mail thoroughly and I converted one
> of the internal docs to Sphinx format, which was against his post. So I
> will weigh in on that now:
>
> There is a distinction between the "docs" and the "website" for each
> project. For LLVM, the website isn't even open source. For Clang and the
> Analyzer, it is in a separate directory from the docs. All the websites are
> currently plain HTML, almost all the code documentation is now Sphinx. It's
> different, and it might be worth considering making the websites Sphinx
> too, but a priori they service different goals so having the website and
> the programming docs in different formats doesn't seem terrible.
>
>
> We were just not clear what were the immediate goals of the clang and llvm
> conversion and if the complete websites (including plain HTML) are being
> converted as well as everything in the docs folder. This seems to be the
> best for constancy, however, it is not clear how much effort is required.
>

I'm not sure how relevant consistency is here, I think of the website as
being the "nice, pretty, easy to navigate" thing. I think of the
documentation as being the "book or guide I would be comfortable printing,
and can also read online". Sphinx is nice for the latter. For the former,
the best thing is a good designer who knows HTML + CSS intimately.

In my mind, it makes total sense for the analyzer website to stay as it is
now (HTML), but all the pages under the user manual to be Sphinx based. My
predicate is "what parts do I want in the printed manual".

 - Daniel


> Currently, most of the analyzer documentation is in plain HTML, so unless
> there are immediate plans on transitioning HTML to Sphinx/RST, we would
> continue committing enhancements in HTML.
>
>
> It makes total sense to me to have the internal documentation browsable on
> the websites somewhere, and this is what we do for LLVM and Clang and all
> the other projects, so I see no reason for the analyzer to be different.
> Note that its only "exposed" as much as there is a URL for it. You can
> decide if and when you want to link to it from the website.
>
>
> Makes sense.
>
>
>  - Daniel
>
>
>
> On Mon, Jan 7, 2013 at 11:19 AM, Daniel Dunbar <daniel at zuster.org> wrote:
>
>> Hi Sean,
>>
>> Thanks, I'll start on this now.
>>
>>  - Daniel
>>
>>
>> On Sat, Jan 5, 2013 at 12:34 PM, Sean Silva <silvas at purdue.edu> wrote:
>>
>>> Hi ddunbar, in transitioning the analyzer to Sphinx, I'm going to need
>>> some setup on the llvm.org server as with the other Sphinx
>>> transitions. As background, clang/docs/analyzer is excluded from the
>>> Sphinx build in clang/docs/, and has its own self-contained Sphinx
>>> build.
>>>
>>> So what is needed is to run `make` inside `clang/docs/analyzer/` (no
>>> `-f Makefile.sphinx` since there was no conflicting Makefile in this
>>> directory), then copy `clang/docs/analyzer/_build/html/` to appear at
>>> <http://clang-analyzer.llvm.org/docs/>.
>>>
>>> Thanks,
>>>
>>> -- Sean Silva
>>>
>>> On Wed, Jan 2, 2013 at 6:19 PM, Sean Silva <silvas at purdue.edu> wrote:
>>> > On Wed, Jan 2, 2013 at 2:56 PM, Anna Zaks <ganna at apple.com> wrote:
>>> >> Would be great to have the analyzer documentation converted, but I
>>> don't
>>> >> know if anyone has committed to do the work.
>>> >
>>> > In r171424 and r171425 I have set up a basic Sphinx setup for the
>>> > analyzer in docs/analyzer/ (segregated from the rest of clang's docs).
>>> > There is no server-side support though so it doesn't currently affect
>>> > the website.
>>> >
>>> > -- Sean Silva
>>>
>>
>>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20130107/a1b6c58b/attachment.html>