From d5e0be4eff9c95a89d7537f2e2471fa0d96d74fb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pipa?= <michal@michalpipa.pl>
Date: Sat, 30 Apr 2016 18:08:34 +0200
Subject: [PATCH 1/2] Fix build instructions

---
 contributing/documentation/format.rst   | 16 +--------------
 contributing/documentation/overview.rst | 26 +++++++++++++++++++++++++
 2 files changed, 27 insertions(+), 15 deletions(-)

diff --git a/contributing/documentation/format.rst b/contributing/documentation/format.rst
index aec7b9d5866..242bc8e7f4f 100644
--- a/contributing/documentation/format.rst
+++ b/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
diff --git a/contributing/documentation/overview.rst b/contributing/documentation/overview.rst
index 1bf32357620..33b318607e9 100644
--- a/contributing/documentation/overview.rst
+++ b/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

From e19a405e20d9a809ef3f5591eaf95e53cb343ac5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pipa?= <michal@michalpipa.pl>
Date: Tue, 3 May 2016 22:41:01 +0200
Subject: [PATCH 2/2] Fix section header

---
 contributing/documentation/overview.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/contributing/documentation/overview.rst b/contributing/documentation/overview.rst
index 33b318607e9..153824f1d3f 100644
--- a/contributing/documentation/overview.rst
+++ b/contributing/documentation/overview.rst
@@ -274,7 +274,7 @@ 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
+Building from Source
 --------------------
 
 If you want to build documentation from source on your local machine, follow