[LLVMdev] Using ReST for documentation

[Keir Mierle]

Just to add an extra note: There is a nice doc generator for Python that
takes ReST docs and produces very nice HTML output. It is now used for the
Python standard library, in addition to many packages.

http://sphinx.pocoo.org/

For example, see:

http://docs.python.org/dev/

Hit 'view source' on the side of some pages (particularly the non-reference
pages) to see what ReST looks like.

While Sphinx doesn't work for documenting C++ API's like doxygen, it is
possible to use it as a way of making general docs via ReST. As an added
bonus, it is very easy to add plugins to ReST and sphinx; for example, I
imagine making a graphviz plugin to visualize CFG's or a pygments plugin for
syntax highlighting LLVM intermediate code would be useful.

Keir

On Tue, Dec 9, 2008 at 7:56 AM, Mikhail Glushenkov <foldr at codedgers.com>wrote:

> [Chris asked me to bring this up on the mailing list some time
> ago, but I couldn't get to it. Sorry for that.]
>
> Since the beginning, I used ReST [1] for documenting llvmc, instead of
> plain HTML that was used historically. In my opinion, ReST is much
> easier to write and read (in the text editor or on terminal); it can
> also be used to produce PDFs, man pages or HTML that looks exactly the
> same as the rest of LLVM documentation (see [2] for example). However,
> there are benefits in having a standardized procedure.
>
> I propose that we allow using ReST (or some other lightweight markup
> language that the majority agrees upon) for new documentation on the
> grounds that this doesn't add too much overhead (generated HTML is
> already used for man pages, for example).
>
> Since it is better to use a single format for documentation, the rest
> of the docs should probably be also converted in the long term.
>
>
>
> [1] http://docutils.sourceforge.net/rst.html
>
> [2] http://llvm.org/docs/CompilerDriver.html
> (Note: this document is out of date; I've updated the style sheet since
> then.)
>
>
> _______________________________________________
> LLVM Developers mailing list
> LLVMdev at cs.uiuc.edu         http://llvm.cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20081209/78d77991/attachment.html>