[LLVMdev] [RFC] Moving to Sphinx for LLVM and friends documentation (with partial implementation (in both 10pt and 12pt font)).
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
* 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.
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.
Click on ``Show Source`` on the righthand side of any page to view the
reStructuredText that generated that page.
Source + Build Directory
#. 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
This email is a valid Sphinx document and can be seen `here
- Michael Spencer
More information about the llvm-dev