Symfony2 Docs in local HTML , ePub and (yes!) PDF

Many people are still searching on Symfony2 Docs site how to download a PDF version as we found at 1.4 version, but saddly there is no one.

I prefer browse in HTML, but of course in the site it’s not the most confortable way.

When I was trying to manually download the docs (monkey job), I’ve found an info about the format used to write the docs, the, o reStrucuturedText:

Symfony – Documentation Format

And there I’ve found how to use Sphinx (not the indexor, but the Python doc generator) to build the docs in HTML, Latex, ePub and PDF.

No PDF till now (update)

But, till now, I was not successfull in build a PDF version. It seems that some [reStrucuturedText] (http://docutils.sourceforge.net/rst.html) syntax extensions used in the docs blocks the right work of rst2pdf. I would try LaTeX, bur is almost a 1Gb download to run the PDF conversion (what is to much for me at this moment). Sorry, no solution by now.

Update in 09/30/2011

Matteo Montanari’s comment (see below) relats success while generating the PDF version with the steps at the bottom of this doc. Thanks, Matteo.

But with browsable HTML and ePub

So let’s prepare the environment, installing python and easy_install (to install Python modules like Perl CPAN or PHP PEAR).

apt-get install python-setuptools python-dev build-essential

Next, install sphinx-pocoo:

easy_install -U Sphinx

Next step is download Symfony2 Docs. Your choice, use git or download the tarball directly from GitHub:

git clone https://github.com/symfony/symfony-docs.git

or

wget https://github.com/symfony/symfony-docs/tarball/master -O symfony-docs.tar.gz

We’ll continue here with the tarball.

Create a directory (your choice, here at tmp as an example):

mkdir /tmp/sf-docs
cd /tmp/sf-docs

Run the Sphinx Quick Start:

sphinx-quickstart

The required fields are:

> Project name: Symfony2Docs
> Author name(s): Symfony Team
> Project version: 2.0.17

Activate also the option to build epub version:

> Do you want to use the epub builder (y/N) [n]: y

The Symfony Docs has a interesting feature – the configuration documentation, which is rendered as tabs. to suport it, it’s necessary to download an extension. (The “7196620” could be diferent for you as is dynamicly generated by the last commit, pay atention!)

mkdir /tmp/sf-docs/_exts
cd /tmp/sf-docs/_exts
wget https://github.com/fabpot/sphinx-php/tarball/master -O sphinx-php.tar.gz
tar xzvf sphinx-php.tar.gz
mv fabpot-sphinx-php-7196620/sensio . 
rm -rf fabpot-sphinx-php-7196620/ 
wget https://raw.github.com/fabpot/sphinx-php/master/configurationblock.py

Configure editing the /tmp/sf-docs/conf.py file – find this line:

extensions = []

and replace for:

sys.path.append(os.path.abspath('_exts'))
from sphinx.highlighting import lexers
from pygments.lexers.web import PhpLexer
extensions = ['sensio.sphinx.refinclude', 'sensio.sphinx.configurationblock', 'sensio.sphinx.phpcode']
lexers['php'] = PhpLexer(startinline=True)
lexers['php-annotations'] = PhpLexer(startinline=True)
primary_domain = 'php'
api_url = 'http://api.symfony.com/master/%s'

Copy the source docs to this directory (the “fac0d42” could be diferent for you as is dynamicly generated by the last commit, pay atention!):

cd /tmp
tar xzvf symfony-docs.tar.gz
cp -R /tmp/symfony-symfony-docs-fac0d42/* /tmp/sf-docs/

and now it’s just build the docs!

HTML

Runs:

cd /tmp/sf-docs/
make html

and it’s to browse via browser in file:///tmp/sf-docs/_build/html/index.html

Tips: you can customize the theme used. See tips in: Sphinx HTML theming support. I used in conf.py:

html_theme_options = {
"rightsidebar": "true",
"stickysidebar": "true"
}

to put sidebar at right and fixed (always visible when rolling the page).

If you want to use the search, put this directory in virtualhost in your web server (it could be at your local machine); now the used JS can search the docs!

ePUB

Run:

cd /tmp/sf-docs/
make epub

and find the e-book in _build/epub

If you want to try the PDF version… (uptdated)

…needs to instal:

apt-get install texlive-full

and so:

cd /tmp/sf-docs/
make latexpdf

I’ve tried the texlive-latex-base packaged ( with ~80Mb insted of ~930Mb of the full packaged) but the PDF was not built. Good look and tell me if you are successfull.

  • got it, excellent! beautiful documentation and it worked fine. The file is only 3MB and it has all.

    Thanks!

  • Pingback: Symfony2 Learning Book | Craft It Online!()

  • Thanx, this was a great start. :-))

    Two remarks:

    a) Someone put a ready-to-go-offline html version on github:

    https://github.com/rafaelgou/symfony-docs-html-local

    b) I installed this LARGE TeX package and yes, you can render a proper PDF (522 pages) from it (drop me a line if you want a copy of it).
    I still got some warnings on missing bundle documents, but this was the same with the html version as well and I think it’s kind of normal (maybe someone else knows it?).

  • Hello Dorthe

    I have just managed to build the pdf file.
    All I needed was the full texlive (texlive-full) and then sphinx gives the latexpdf option which does the job.

    It’s pretty good result.
    I am happy with it.

  • Michaël P.

    I manage to generate pdf with the following packages (approximately 9Mo):

    texlive-common texlive-latex-base texlive-latex-recommended texlive-latex-extra

    But I have a serious problem with the epub version I generate. The epub file contain just the table of contents and the index, but content at all.

    Very frustrating!

    • fran’

      Same problem. Don’t know why ? An idea ? Thanks

  • Jack Smith

    PDFs give a good conversion quality of conversion better than a word file my own file conversion with word was very difficult, I ordered my book to conversion from http://www.ebookconversion.com/

  • toetip

    Hey !
    thanks for you tutorial.

    I got a problem with epub generation (from sf sources or even from your repo on github) : I always got a ten pages long epub.

    As a sphinx newbie, I must have miss something. Did you got the same issue ? if no, could you explain howto build ?

    thanks

  • ZoRDoK

    I too got 11 page epub – table of context only

  • Enrico Marongiu

    The .epub file is just the TOC with all the documents referenced as local html files.
    Curiously, converting the .epub in .mobi (with Calibre) I managed to obtain a fully functional and self consistent kindle-friendly ebook.
    Perhaps converting it back to .epub may be a workaround 🙂

  • Pingback: How to build a kindle friendly Symfony2 documentation ebook | Enrico Marongiu()

  • Hey there. I discovered your website the use of msn. It is really an extremely well written content. I’m going to ensure that you book mark this and are avalable back to discover more within your practical information and facts. Many thanks for the particular publish. Let me unquestionably go back.

  • Hello,

    I successfully generated an epub for Symfony Docs 2.3.4 using your method (on Windows).

    However, I have 2 small issues :
    1) https://raw.github.com/fabpot/sphinx-php/master/configurationblock.py doesn’t exist. Is it important to download it and what should be done with it ?

    2) when generating ePub, I got some warnings from sphinx :
    bundles/map.rst.inc:1: WARNING: unknown document: /bundles/SensioFrameworkExtraBundle/index
    bundles/map.rst.inc:2: WARNING: unknown document: /bundles/SensioGeneratorBundle/index
    bundles/map.rst.inc:3: WARNING: unknown document: /bundles/DoctrineFixturesBundle/index
    bundles/map.rst.inc:4: WARNING: unknown document: /bundles/DoctrineMigrationsBundle/index
    bundles/map.rst.inc:5: WARNING: unknown document: /bundles/DoctrineMongoDBBundle/index

    Thank you