[LLVMdev] Using ReST for documentation

[Talin]

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
  --------------------

  Another useful statement is the :stmt:`with` statement::

    // Declare a new variable 'fh' and assign an open file handle to it.
    with fh = File.open("unicode.txt) {
      // Do something with fh.
      // It will be closed when the block exits.
    }
 
  The :stmt:`with` statement can be used to guarantee that the appropriate
  cleanup code is called after you are finished with an object. In the above
  example, the file handle ``fh`` will be closed upon exit from the
  :stmt:`with` block, regardless of how the block was existed (even if via
  :stmt:`return` or an exception.)

  The :stmt:`with` statement can also influence the set of effect 
annotations
  that propagate outward from within the contained block. Similar to the 
way a
  :stmt:`try` statement can filter out an exception effect, a :stmt:`with`
  statement that acquires and then releases a mutex could potentially
  remove a 'thread-unsafe' effect.

The ":stmt:" modifier creates inline hyperlink to the documentation for 
the specified statement. It also generates an entry in the index under 
"Statements".

The indented code example will be automatically syntax-colored. In this 
case, its using a custom syntax definition for the language I am 
writing, however there are syntax definitions available for several 
dozen popular languages already. (It would be relatively easy, for 
example, to create a syntax definition for LLVM IR.)

Sphinx was originally written to solve the problem of documentation in 
Python. For many years, the Python reference manuals were written in 
LaTeX. The problem with this is that it made it difficult to get 
contributors to submit documentation patches. Few people know LaTeX 
these days, and the tool chain for producing HTML from LaTeX sources is 
complex and difficult to install and use.

Georg Brandl, the creator of Sphinx, wrote a LaTeX-to-ReST converter, 
and converted all of Python's documentation to ReST. He also provide the 
tools needed to convert and maintain the documentation. Since that time, 
the number of outside contributions to the Python documentation has 
increased dramatically. (I don't have exact stats, but I could probably 
get them if needed.)

It was because of this experience with Python that I decided to give 
Sphinx a try with my own docs. So far I have been quite pleased with the 
results.

Here's the main Sphinx site:

   http://sphinx.pocoo.org/

I highly recommend browsing some of the examples and looking at other 
projects using Sphinx.

-- Talin

Tanya Lattner wrote:
> 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
>
> On Dec 9, 2008, at 7:56 AM, Mikhail Glushenkov 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
>>     
>
> _______________________________________________
> LLVM Developers mailing list
> LLVMdev at cs.uiuc.edu         http://llvm.cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev
>
>