The Symfony site gives brief information on how to build the Symfony2 documentation, but I felt it lacked some of the finer details for anybody who might be new to reStructuredText documents. I decided to put up a blog post after trying to find a more detailed explanation and failing – I hope this helps others who have also just started using ReST files.
Firstly, we need to install some required software packages.
Open up a terminal and install the python packages:
apt-get install python-setuptools python-dev build-essential
Next install the gargantuan LaTeX. LaTeX is a document preparation system that weighs in at over 1Gb. This is required to build the reStructuredText as PDF.
apt-get install texlive-full
Lastly, we install Sphinx, the python documentation generator
easy_install -U Sphinx
Initialise the Symfony2 Documentation directory
I personally like to keep the generated files under /var/www/symfony2docs as I create a vhost that points to the built HTML to browse whether I’m online or offline.
To mimic this, run:
mkdir /var/www/symfony2docs cd /var/www/symfony2docs sphinx-quickstart
The command sphinx-quickstart will run a project setup wizard. You can safely just press Enter to accept the defaults showing between [ ] brackets.
There are, however, four options that will require input. I fill them in as follows:
- Project Name: Symfony2 Documentation
- Author Name(s): SensioLabs
- Project Version: 2
- Do you want to use the epub builder (y/N) [n]: y
The question regarding the epub builder is set to “n” by default. Change this option to “y” if you would also like to build the documentation into an epub format.
Install SensioLab’s configuration-block Sphinx extension
To install the extension, run the following:
mkdir /var/www/symfony2docs/_exts cd /var/www/symfony2docs/_exts wget https://raw.github.com/fabpot/sphinx-php/master/configurationblock.py
Next, we have to activate the extension by editing the conf.py file.
extensions = 
sys.path.append(os.path.abspath('_exts')) # Activating the configurationblock extension extensions = ['configurationblock']
Download latest Symfony2 Documentation
We have two ways of retrieving the latest Symfony2 Documentation – either using Git or by downloading the latest tarball.
I usually download the latest documentation into the /tmp directory and then copy it into the Sphinx project from there. Git creates symfony-docs directory whereas, the tarball creates a directory named symfony-symfony-docs-xxxnnnn (e.g. symfony-symfony-docs-dfe0182). If using the tarball please verify the name of the folder created when unpacking the archive.
If using Git, run:
cd /tmp git clone https://github.com/symfony/symfony-docs.git mv /tmp/symfony-docs/* /var/www/symfony2docs
If using the tarball, run:
cd /tmp wget https://github.com/symfony/symfony-docs/tarball/master -O symfony-docs.tar.gz tar -zxvf symfony-docs.tar.gz mv /tmp/symfony-symfony-docs-dfe0182/* /var/www/symfony2docs
Build Symfony2 Documentation PDF
We finally have all the files in the right locations to build the PDF.
cd /var/www/symfony2docs make latexpdf
The output can be found in the _build directory
Build Symfony2 Documentation HTML
cd /var/www/symfony2docs make html
Build Symfony2 Documentation EPUB
cd /var/www/symfony2docs make epub