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

[Anna Zaks]

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.

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/852c2aca/attachment.html>