Compound Thinking

Sphinx and TG2 docs

We’re hard at work trying to make the TurboGears 2 docs into something best in class. There’s a long way to go, but the toolchain we’re using keeps getting better and better thanks to Sphinx and Bruno José de Moraes Melo and his GSoC work.

Sphinx all by itself provides a great system for turning ReStructured Text (ReST) files into usable documentation. Since the TG docs were in MoinMoin already, and we’d been careful to use ReST, getting started with sphinx was pretty easy. We updated the doc strings in TG2 to take advantage of the sphinx autodoc features to do API level documentiaton.

But the missing piece was pulling example code in from working sample projects. Sphinx had some include helpers, but they weren’t flexible enough for our needs. So, Bruno has created a set of sphinx extensions to help us. The first of these imports working files from projects checked into subversion. This allows us to show progressive enhancement of projects, and it allows us to keep the working example code under the same source control system as the docs.

So now our Wiki20 source doc has sections that look like this:

.. code:: Wiki-20/wiki20/controllers/root.py
   :revision: 4831

Thanks to the sphinx goodness the code this pulls in is going to be color coded for automatically. Bruno has also added the ability to mark of specific snipits of source code so that you can import just the bit you want to show off like this:

.. code:: Wiki-20/wiki20/templates/page.html
    :revision: 4831
    :section: PageName

and where the PageName section is marked off like this:

<!-- ##{PageName} -->
    Page Name Goes Here
<!-- ## -->

Bruno is working on a few more extensions to sphinx, that automatically test project code before adding it to the doc, and that automatically zip up the sample project and make it available so that documentation uses can easily download it.

I’m pretty excited about how the docs are shaping up, and I’m hoping that a few more people get involved in writing good docs, because the TG team is very much committed to trying to have the best possible docs. Docs aren’t sexy, but good docs can make or break a the use of a framework for new users getting started, and advanced students who are trying to do complex things.