Django Documentation in ePub Format

The Django documentation is now available in ePub format, thanks to Read the Docs. Because the Django documentation is written using Sphinx, we can generate HTML, PDF, and ePub out of the box. However, it’s necessary some tweaking to make Sphinx generate a better looking ePub. In this post I’ll share some of the changes I did. You can check this post for more details.

By default Sphinx shows a navigation bar and spells out the urls in links. Also, by some crazy reason, I get an error when viewing the ePub file provided by the Django website (using iBooks). In the following images we can see the ePub from the Django website on the left and the one I generated on the right:

navigation no-navigation

By default Sphinx adds a copyright footer after every chapter. Since I find it superfluous, I’ve removed it on the theme I use. Again, the ePub from the Django site is on the left and the one I generated on the right:

footnote no-footnote

The biggest change I’ve made was excluding content. I found that reading technical documents on a tablet can be difficult because it’s not as easy to jump around. Therefore, to make the ePub more manageable, I decided to exclude in the final file the glossary, the release notes, the index, and the deprecated and obsolete documentation. Naturally, I find all these documentation items relevant and important, but I find that I need to refer to them less often, making them available on the ePub less necessary (and I’m glad I can access them online anytime I want). Also, I changed the depth of items in the TOC from 3 to 2 to make it more manageable on a tablet:

toc

I used Anonymous Pro as the font of the code examples.

code

And finally, a quick cover to make it prettier ;-)

cover

You can download the ePub for the 1.4 version and the upcoming 1.5 version. Please keep in mind that these files are somewhat experimental; I generated them for my own use. Let me know in the comments if you find any problems. The code is on github on the branches stable/1.4.x and stable/1.5.x, respectively.

  • jethar

    I was trying to generate the epub, using the above instructions, but get the following error:

    writing output… [ 0%] contents
    Exception occurred:
    File “…/Sphinx-1.2.2-py2.7.egg/sphinx/builders/epub.py”, line 377, in write_doc
    self.add_visible_links(doctree, self.config.epub_show_urls)
    TypeError: add_visible_links() takes exactly 2 arguments (3 given)

    I have tried on both python ver 2.7.5 and 3.2.2.

    I tried with commands : make epub
    and also with
    sphinx-build -b epub2 srcdir builddir

    What am I doing wrong here?
    thanks in advance…

    • pedrokroger

      My code is oldish. Probably add_visible_links changed to accept more arguments.