zc.buildout recipe to build your Sphinx doc

Sphinx is now used by quite a few communities : Python, Django, Pylons, Grok (not sure about the current status), …

No wonder, it’s a blast.

We are now starting to use it to produce customer documentation for our buildout-based applications. Basically, a Sphinx structure is created in the buildout using sphinx-quickstart, and a few tweaks are made so the HTML and PDF outputs have a custom look.

Managing the documentation like the code makes life easier. This is one of the basic rule of agile documentation : separate the content from the layout, so you can provide documentation in any shape (html, pdf) with a single source.

To make things easier, I have released collective.recipe.sphinxbuilder.

This recipe:

• creates for you a Sphinx-based documentation in your buildout
• creates a single script in the bin folder to build the documentation with one command
• provides an extensive set of options to drive Sphinx from buildout

Adding it in your buildout is as simple as :

[buildout]
parts =
  sphinx

[sphinx]
recipe = collective.recipe.sphinxbuilder

I have also customized the look and feel of the output so it uses the Plone logo and a custom css. This is configurable from the buildout configuration file of course. By the way, if someone from the Plone community wants to improve the CSS, please dot it ! (I am not good at this )

Plone look for Sphinx Documentation – HTML

Plone look for Sphinx documentation – PDF

Notice that if you use LaTex or PDF rendering, you will need to install pdflatex. Furthermore, the recipe script will not work under Windows unless you install a Linux-like environment, since it uses the Makefile provided by Sphinx. I guess MSYS+MinGW should make it work, but I didn’t try.