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

[Daniel Dunbar]

Hi Michael,


Awesome work!

I'm a strong supporter of using Sphinx. I've been using it for the LNT
docs (http://llvm.org/docs/lnt/) and it is quite nice to work with. +1
for migrating over.

 - Daniel

On Sun, Aug 8, 2010 at 11:29 PM, Michael Spencer <bigcheesegs at gmail.com> wrote:
> 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
> _______________________________________________
> LLVM Developers mailing list
> LLVMdev at cs.uiuc.edu         http://llvm.cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev
>