Peter Hoffmann, 02.09.2012 21:35:

I have started to port[0] the documentation to sphinx. As I have read[1] on the mailling list that's a task where help would be appreciated.

Definitely! Thanks for picking it up.

Because the documentation is already in rst format, an initial build with sphinx was easy and the result[2] looks quite promising.

The next steps will be:

* remove markup specific to the current build system and replace it with sphinx idioms

Most of that should be doable with a straight forward search & replace. But try to be a bit careful that the PDF generation can still work afterwards. Don't use Sphinx features carelessly, because they won't be available for the PDF.

* fix pdf generation

You can give rst2pdf a try. I prefer it over rst2latex these days. Sphinx won't help much with PDF generation anyway.

* use sphinx for api documentation (with sphinx autodoc where possible)

Not sure how well that will work. Lxml relies on an epydoc feature that parses the signature from the first line in the docstring (because most tools don't bother figuring out the signatures of Cython implemented functions). No idea how Sphinx handles this.

* theme/layout

Sounds like the last thing to care about, but making it look good in addition to making it work is never wrong. ;) Stefan