Fix build instructions

Author: michalpipa

contributing/documentation/format.rst

@@ -27,7 +27,7 @@ tutorial and the `reStructuredText Reference`_.
 Sphinx
 ------
 
-Sphinx is a build system that provides tools to create documentation from
+Sphinx_ is a build system that provides tools to create documentation from
 reStructuredText documents. As such, it adds new directives and interpreted text
 roles to the standard reST markup. Read more about the `Sphinx Markup Constructs`_.
 
@@ -198,20 +198,6 @@ reached end-of-maintenance will be removed. For example, if Symfony 2.5 were
 released today, and 2.2 had recently reached its end-of-life, the 2.2 ``versionadded``
 tags would be removed from the new ``2.5`` branch.
 
-Testing Documentation
-~~~~~~~~~~~~~~~~~~~~~
-
-When submitting a new content to the documentation repository or when changing
-any existing resource, an automatic process will check if your documentation is
-free of syntax errors and is ready to be reviewed.
-
-Nevertheless, if you prefer to do this check locally on your own machine before
-submitting your documentation, follow these steps:
-
-* Install Sphinx_;
-* Install the Sphinx extensions using git submodules: ``$ git submodule update --init``;
-* Run ``make html`` and view the generated HTML in the ``_build/html`` directory.
-
 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
 .. _Sphinx: http://sphinx-doc.org/
 .. _`Symfony documentation`: https://github.com/symfony/symfony-docs

contributing/documentation/overview.rst

@@ -274,6 +274,28 @@ page on GitHub and click on ``Details``.
     Only Pull Requests to maintained branches are automatically built by
     Platform.sh. Check the `roadmap`_ for maintained branches.
 
+Building from source
+--------------------
+
+If you want to build documentation from source on your local machine, follow
+these steps:
+
+**Step 1.** Install pip_ (follow the `pip installation`_ chapter).
+
+**Step 2.** Install Sphinx_ and `Sphinx Extensions for PHP and Symfony`_.
+
+.. code-block:: bash
+
+    $ pip install sphinx~=1.3.0 git+https://github.com/fabpot/sphinx-php.git
+
+.. caution::
+
+    You should install Sphinx and Shpinx extensions globally on your system. It
+    means that above command should be executed as root user.
+
+**Step 3.** Run ``make html`` and view the generated HTML in the ``_build/html``
+directory.
+
 Minor Changes (e.g. Typos)
 --------------------------
 
@@ -346,4 +368,8 @@ definitely don't want you to waste your time!
 .. _`Symfony Documentation Badge`: https://connect.sensiolabs.com/badge/36/symfony-documentation-contributor
 .. _`sync your fork`: https://help.github.com/articles/syncing-a-fork
 .. _`Platform.sh`: https://platform.sh
+.. _pip: https://pip.pypa.io/en/stable/
+.. _`pip installation`: https://pip.pypa.io/en/stable/installing/
+.. _Sphinx: http://sphinx-doc.org/
+.. _`Sphinx Extensions for PHP and Symfony`: https://github.com/fabpot/sphinx-php
 .. _`roadmap`: https://symfony.com/roadmap