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 ISMe, 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.
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.
Getting Sphinx to build your e-book
The Makefile generated by Sphinx does not include epub build out of the box. But you can easily add the following rule to the Sphinx-generated Makefile:
epub: $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub @echo @echo "Build finished. The e-Pub pages are in $(BUILDDIR)/epub."
… and voilà, you can now build an epub-formatted e-book by simply typing:
$ make epub
If you are on Windows, you can achieve the same effect by editing
make.bat and doing the equivalent changes there.
And here is the resulting book. Looks great in my reader, and has a nice table of contents. For an experimental support, the result is very accomplished. My congrats to he Sphinx authors!