Generating e-books with Sphinx

Sphinx

I find Sphinx a great tool for writing technical documentation. Born with the purpose of writing the Python documentation at docs.python.org, Sphinx specially excels at generating HTML for text-intensive documents that include code samples.

Although part of the Python ecosystem, there is nothing that binds Sphinx to just documenting Python programs. We use it at Isigma e.g. for documenting the integration APIs for our applications, such as PortaSigma or ISM^e, which are mostly Java.

Sphinx serves as a good complement to in-code documentation tools like Javadoc/Doxygen/Epydoc, and is very well suited for writing programming tutorials and technical documents or books.

e-books

I recently started playing around with e-book readers and getting acquainted with the possibilities of developing software for these devices. I just started to familiarise myself with the epub format, which seems to be the best-suited format for e-books. For practical purposes, an epub file is just a ZIP file containing HTML, CSS and XML files. Which got me thinking, wouldn’t it be nice to be able to convert Sphinx documentation into an e-book?

I browsed the Sphinx documents and voilà, the epub format is stated to be available in experimental stage. You just have to do a specific build for it. It turned out to be extremely simple.