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

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
>

On Mon, Aug 9, 2010 at 3:00 PM, Adve, Vikram Sadanand
<vadve at illinois.edu> wrote:
> 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.
I agree that they are currently difficult to navigate. I was planning
on removing the inline TOC and just use the Sphinx generated one on
the right hand side. Also, the font size is larger and there is less
horizontal space. The size and space is a trivial change, but I was
also thinking about other changes to the structure of the
documentation itself to better fit in this format. The current
documentation is really structured as a collection of semi-related
papers. Any suggestions here would be very welcome.
> --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
>>