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.

Install packages

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.

Search for:

extensions = []

Replace with:

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
Be Sociable, Share!