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.<br><br><a href="http://sphinx.pocoo.org/">http://sphinx.pocoo.org/</a><br>
<br>For example, see:<br><br><a href="http://docs.python.org/dev/">http://docs.python.org/dev/</a><br><br>Hit 'view source' on the side of some pages (particularly the
non-reference pages) to see what ReST looks like.<br><br>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.<br>
<br>Keir<br><br><div class="gmail_quote">On Tue, Dec 9, 2008 at 7:56 AM, Mikhail Glushenkov <span dir="ltr"><<a href="mailto:foldr@codedgers.com">foldr@codedgers.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
[Chris asked me to bring this up on the mailing list some time<br>
ago, but I couldn't get to it. Sorry for that.]<br>
<br>
Since the beginning, I used ReST [1] for documenting llvmc, instead of<br>
plain HTML that was used historically. In my opinion, ReST is much<br>
easier to write and read (in the text editor or on terminal); it can<br>
also be used to produce PDFs, man pages or HTML that looks exactly the<br>
same as the rest of LLVM documentation (see [2] for example). However,<br>
there are benefits in having a standardized procedure.<br>
<br>
I propose that we allow using ReST (or some other lightweight markup<br>
language that the majority agrees upon) for new documentation on the<br>
grounds that this doesn't add too much overhead (generated HTML is<br>
already used for man pages, for example).<br>
<br>
Since it is better to use a single format for documentation, the rest<br>
of the docs should probably be also converted in the long term.<br>
<br>
<br>
<br>
[1] <a href="http://docutils.sourceforge.net/rst.html" target="_blank">http://docutils.sourceforge.net/rst.html</a><br>
<br>
[2] <a href="http://llvm.org/docs/CompilerDriver.html" target="_blank">http://llvm.org/docs/CompilerDriver.html</a><br>
(Note: this document is out of date; I've updated the style sheet since<br>
then.)<br>
<br>
<br>
_______________________________________________<br>
LLVM Developers mailing list<br>
<a href="mailto:LLVMdev@cs.uiuc.edu">LLVMdev@cs.uiuc.edu</a>         <a href="http://llvm.cs.uiuc.edu" target="_blank">http://llvm.cs.uiuc.edu</a><br>
<a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev" target="_blank">http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev</a><br>
</blockquote></div><br>