[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
<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



More information about the llvm-dev mailing list