Skip to main content

Create an epub with Symfony documentation

If you’re a good PHP developer you should know something about Symfony and what better way to do it than reading an epub? In this article I want to show you how to produce an epub with Symfony documentation for any supported version.

Online documentation

First of all, you don’t need to build an epub: the documentation is already available online in HTML and PDF format.

But since I have an ebook reader and want to make the most of my waiting time, I just thought to create an epub for it.

Putting together stuff by using the correct tools is always rewarding, so the process itself has been fun!

Get the documentation

You may have guessed it: all the Symfony documentation is available as a project on GitHub in RST format.

This format basically make it easy to convert to any other format.

The repo is https://github.com/symfony/symfony-docs.

So first of all you just clone the repo, and checkout the branch for the version you want to read about.

Install Sensio extension

All the required configuration to make an epub (and also other formats) is already included in the repo, except – for reasons yet unknown to me – for the Sensio extension for Sphinx.

Oh, BTW, Sphinx (http://sphinx-doc.org/) is a tool to create documentation and the Sensio extension is, well, an extension for it specifically written for PHP and Symfony by Fabien Potencier himself.

Aren’t you learning a lot just by reading the procedure?

Make epub

No, really, that’s the command:

make epub

That’s all you need to do to produce the epub. Almost.

Calibre to the rescue!

The generated epub won’t be perfect; in fact, it will only be a table of content with links that open external HTML file.

Not exactly what you want, then.

But if you read epub you definitely use Calibre (or you should anyway) and if you use Calibre you can just convert from epub to epub to let it do its magic.

Acknowledgements

Thanks to the Symfony team for taking the trouble to create all documentation in an open format.

Thanks to the Calibre team for their invaluable tool.

Thanks to all other open source tools that one ends up using during the procedure (RST, Sphinx, Python, ecc…).

Thanks to Enrico Marongiu because his article did not work for me but pointed me in the right direction 🙂