How to build a kindle friendly Symfony2 documentation ebook [Updated]

As a proud Kindle keyboard owner, I use it to read both leisure books and tech-related readings.

Albeit Kindle keyboard supports PDF documents, my eyes do not support reading a pdf formatted for A4 or Letter. Fonts are incredibly small and the zoom feature is almost useless.

That is the case for the Symfony2 documentation. It is a nice PDF ebook, which is great to see on PC, but things get awry on Kindle.

Googling a bit, I found that Symfony documentation:

Ok, .epub is not kindle friendly, but with Calibre you can convert .epub into .moby with decent results (usually).

I started enthusiastically to self produce my ebook, but things have gone a bit more complicated on my windows 7 pc: here is the history.

 

Install python 3.3 32 bit binary… OK

Install distribute in place of easy_install… OK

Install sphinx from a local file downloaded from the Python package index, crossing fingers on python version compatibility… OK

Follow the instructions for “testing documentation” as suggested on the Symfony documentation guidelines, except that I wanted to “test” the existing documentation (and produce the .epub file):

1) clone the git doc repo,

2) save the index.rst for better times

3) run sphinx “quick_setup”

4) install the sensio extension

5) restore the original Symfony index file

6) edit conf.py as suggested in the Symfony documentation guidelines

7) run

GOSH! several exceptions were raised by the python interpreter.

Luckily, all the fuss was about the “lower” and “upper” string functions (methods?) in the Sensio extension.

Being not a Python expert, I just managed to edit some lines and got everything work, eventually. Here are the details:

In phpcode.py

– comment the line

– look for

function and replace it with

In configurationblock.py

– comment the line

– look for

function and replace it with

 

Run again make epub and watch it doing the magic. Then, open calibre, import the .epub file and convert it into .mobi.

 

Curiously, the .epub file seems to contain the table of contents in .epub format and all the contents in html. Calibre opens them on the default browser, while FBreader seems not able to manage the format.

 [UPDATE 2013-03-19 16:00 UTC+1]

After some consideration I decided to share with you the Symfony2.2 book in .mobi format. I preserved the original copyrights and all rights are reserved by the copyright holder.