Using ReST for documentation

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

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

Can you compare ReST to docbook? We've talked about using docbook for a long time. What are the pros and cons of each?

Thanks,
Tanya

WikiFormatting for code documentation? :slight_smile:

-scooter

I have no docbook experience. However, there is a ReST to docbook converter available: http://docutils.sourceforge.net/sandbox/oliverr/docbook/

Keir

Another alternative with wikiformating producing docbook is Quickbook:
http://www.boost.org/doc/libs/1_37_0/doc/html/quickbook.html

However, I am not advocating this tools, I just wanted to mention it in the discution. The main advantage is good C++ integration but the doc build chain is long and don't work so well. I expect this to change as boost is moving most of its documentaiton to this format.

Cédric

Scott Michel a écrit :

I've been using Sphinx, the tool Kier mentions, for my own documentation needs. I've been using it for over six months and so I am fairly familiar with it.

ReST is, as mentioned, is a markup language that is inspired by WikiNotation, but more targeted at producing technical documentation rather than informal collaborative editing of web pages. Sphinx extends ReST in this direction even further, providing markup elements for functions, classes, methods, statements, macros, and other programming constructs -- essentially it defines a set of semantic markup conventions which are represented in ReST syntax.

The major advantage of ReST over HTML or LaTeX is that the source documentation is readable as text. The markup conventions are lightweight and minimal, avoiding clutter, yet completely deterministic and rigorous in meaning. Here's a sample taken from my own documentation:

  The "with" statement

Can you compare ReST to docbook? We've talked about using docbook for
a long time. What are the pros and cons of each?

I have no experience with DocBook, but it seems that since it is XML-based it
should also suffer from verbosity issues. For example, the Boost project, which
originally used plain DocBook, decided to build a new ReST-like documentation
format[1] on top of it.

[1] http://www.boost.org/doc/libs/1_37_0/doc/html/quickbook.html

I have to give a vote for Boosts QuickBook as well. Nicely made
system with a few code related features (considering it is used for
documenting C++ libraries).

Quickbook is very cool. The last time I tried it it was extremely hard to use
outside the Boost environment. This was over a year ago and at the time
there was discussion about amking it an indepoendent tool. I don't know
what state it's in.

The really cool thing about Quickbook is the doxygen integration. Quickbook
converts to BoostBook, which is an extension of DocBook that includes tags
for making API manuals and such.

                                               -Dave