How to generate symfony 2 documentation

Symfony 2 is a PHP 5.3 Framework by Sensiolabs. As it's still in development stage and I want to be able to read about newest features, especially from other branches of documentation. I fall in doubt how to read an .rst docs. First what i found was a python-docutils. But it's utility rst2html converts only one rst file! Then I found that Fabien uses sphinx to generate docs.

Preparations

First of all you need to have git installed. I will use Ubuntu installation in this example. But I think everything should be almost same on other Linux.

git clone https://github.com/symfony/symfony-docs.git
git clone https://github.com/fabpot/sphinx-php.git

First line will clone a Symfony 2 documentation and second one will clone an extension for viewing different code snippets. You can use sphinx-builder as is. But you will not see some parts. Next you need a python-setuptools installed:

sudo apt-get install python-setuptools
sudo easy_install -U Sphinx

Second command will install Sphinx (sphinx-build, sphinx-quickstart and sphinx-autogen). You can use a default Ubuntu shinx-build but I found it's outdated.

Let's build it!

Now all is ready. Let's do it. Prepare to answer questions about how you want to have all documentation built. To just read documentation you can answer all questions as their defaults.

cd symfony-docs
cp index.rst index_.rst
sphinx-quickstart

You need to copy index.rst, as program assumes you are just starting with documentation.
After you have answered all questions you need to copy back an index.rst

mv index_.rst index.rst

Now you need to add an extension from sphinx-php repository. Just open config.py with your favorite editor and add after code import sys, os:

sys.path.append(os.path.abspath('../sphinx-php'))

And add extension to extensions hash:

#was before
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.pngmath']
#after
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.pngmath', 'configurationblock']

If you have selected to make a Makefile you are ready to go with building a doc with.

make html

This will generate a doc in _build/html/index.html If you choose not to make a Makefile:

sphinx-build -b html ./ ./_build/html

That's it!