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

Michael Spencer bigcheesegs at gmail.com
Sun Aug 8 23:29:47 PDT 2010

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
and fixed minor porting issues.

Here are the links to the current documentation and associated files.

Current Docs

  Click on ``Show Source`` on the righthand side of any page to view the
  reStructuredText that generated that page.

Configuration File

Source + Build Directory

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.


This email is a valid Sphinx document and can be seen `here

- Michael Spencer

More information about the llvm-dev mailing list