[LLVMdev] [RFC] Moving to Sphinx for LLVM and friends documentation (with partial implementation (in both 10pt and 12pt font)).

[Adve, Vikram Sadanand]

Michael,

The benefits of Sphinx sound nice but one comment: The main page and the tables of contents in the other pages (at least the ones I looked at: Getting Started; Lang Ref) are so long and sparse that it is difficult to get the big picture of what is there and even to find a document unless you know what to search for.  The originals were much more compact and so much better in this regard.

--Vikram
Associate Professor, Computer Science
University of Illinois at Urbana-Champaign
http://llvm.org/~vadve



On Aug 9, 2010, at 12:00 PM, <llvmdev-request at cs.uiuc.edu> wrote:

> Date: Mon, 9 Aug 2010 02:29:47 -0400
> From: Michael Spencer <bigcheesegs at gmail.com>
> Subject: [LLVMdev] [RFC] Moving to Sphinx for LLVM and friends
>        documentation (with partial implementation (in both 10pt and 12pt
>        font)).
> To: llvmdev <llvmdev at cs.uiuc.edu>
> Message-ID:
>        <AANLkTim_YuGaHPjOpTDG=XwoxvUk1qL+H8wfEF+VgxGp at mail.gmail.com>
> Content-Type: text/plain; charset=UTF-8
> 
> Moving the LLVM Documentation to Sphinx
> =======================================
> 
> As a few of you that are on IRC already know, I have experimented with moving
> the LLVM documentation over to `Sphinx <http://sphinx.pocoo.org/index.html>`__
> from the current html form. I have moved almost all of the content over and have
> begun "Sphinxifying" the documentation to correct links and make use of the many
> features that Sphinx provides.
> 
> What is Sphinx?
> ---------------
> 
> To quote from the Sphinx website:
> 
>  Sphinx is a tool that makes it easy to create intelligent and beautiful
>  documentation, written by Georg Brandl and licensed under the BSD license.
> 
>  It was originally created for the new Python documentation, and it has
>  excellent facilities for the documentation of Python projects, but C/C++ is
>  already supported as well.
> 
>  Sphinx uses reStructuredText as its markup language, and many of its strengths
>  come from the power and straightforwardness of reStructuredText and its
>  parsing  and translating suite, the Docutils.
> 
> 
> What Does Sphinx Do For LLVM?
> -----------------------------
> 
> * Creates a unified documentation infrastructure. Sphinx can create man pages,
>  which we are currently using a seperate format to do. There is also work on
>  integrating doxygen.
> * Is pretty (both the source and output).
> * Is easier to edit and maintain than html.
> * Is extensible via Python.
> * Uses `Pygments <http://pygments.org/>`__ for syntax highlighting, which
>  supports LLVM IR.
> * Provides a rather good search engine.
> 
> 
> Current Status
> --------------
> 
> Currently I have simply moved the html and pod docs over to reStructuredText
> using a modified version of `html2rst
> <https://www.dropbox.com/s/pqzwlxvwjbvm4xq/html2rest.py#>`__ and `pod2rst
> <http://search.cpan.org/~dowens/Pod-POM-View-Restructured-0.02/bin/pod2rst>`__
> and fixed minor porting issues.
> 
> Here are the links to the current documentation and associated files.
> 
> Current Docs
>  https://dl.dropbox.com/u/9889801/llvm-sphinx-docs/_build/html/index.html
> 
>  Click on ``Show Source`` on the righthand side of any page to view the
>  reStructuredText that generated that page.
> 
> Configuration File
>  https://www.dropbox.com/s/vdgl8hhkojujv19/conf.py
> 
> Source + Build Directory
>  https://www.dropbox.com/s/jlo7adms1890e56
> 
> 
> What's Left?
> ------------
> 
> #. Finish moving over the docs.
> #. Finish Sphinxifying them.
> #. Pick the paint color for the bike shed. I have done no work on this other
>   than copying over the default ``sphinxdoc`` theme to the source dir as
>   ``llvm-theme``. Creating Sphinx themes is actually rather easy, so anyone is
>   welcome to take a stab at this if they wish.
> #. Integrate building the docs into the autoconf and CMake build systems.
> 
> 
> What Do You Think?
> ------------------
> 
> I realize that changing the documentation format is non-trivial, but I believe
> that the benefits are worth the effort. If we go forward with this I will finish
> the first two points above and work to integrate doxygen and keep everything
> running smoothly.
> 
> 
> BTW
> ---
> 
> This email is a valid Sphinx document and can be seen `here
> <http://dl.dropbox.com/u/9889801/llvm-sphinx-docs/_build/html/meta-sphinx-
> documentation.html>`__.
> 
> 
> 
> - Michael Spencer
>