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.
- 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 :
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 :) )
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.