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

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.

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!

Advertisements

2 thoughts on “Generating e-books with Sphinx

  1. Do you have any thoughts about using sphinx for a complete textbook? I have written a 500+ page textbook on assembly language using LaTeX and would like to convert it to ePub. I have been working on converting it to DocBook and just learned about Sphinx, which seems much simpler.

  2. I tried to generate an epub from this https://launchpad.net/thinkcspy but only shows the index and toc. The weird part is that converting this crippled epub to mobi works, the mobi looks just fine. I opened the epub like a zip file and all the content is all there but no reader can read it :S not even calibre.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s