[LLVMdev] [RFC] Moving to Sphinx for LLVM and friends documentation (with partial implementation (in both 10pt and 12pt font)).
daniel at zuster.org
Mon Aug 9 13:06:59 PDT 2010
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.
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
> 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
> LLVM Developers mailing list
> LLVMdev at cs.uiuc.edu http://llvm.cs.uiuc.edu
More information about the llvm-dev