minor #6835 Updated the instructions to build docs locally (javiereguiluz)

This PR was merged into the 2.7 branch.

Discussion
----------

Updated the instructions to build docs locally

This finishes #6395.

Commits
-------

a2428a4 Minor improvements
914dd30 Fixed the "make" command
77c88bf Fixed again the tricky list syntax
767b49b Fixed the syntax of the list
c71ad4b Minor fixes
a7b4d32 Reword the third step
cebc382 Added the missing link references
348b11c Updated the instructions to build docs locally

Author: weaverryan

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

@@ -258,6 +258,33 @@ link displayed for Platform.sh service.
     Only Pull Requests to maintained branches are automatically built by
     Platform.sh. Check the `roadmap`_ for maintained branches.
 
+Build the Documentation Locally
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Alternatively you can build the documentation in your own computer for testing
+purposes following these steps:
+
+#. Install `pip`_ as explained in the `pip installation`_ article.
+
+#. Install `Sphinx`_ and `Sphinx Extensions for PHP and Symfony`_
+   (depending on your system, you may need to execute this command as root user):
+
+   .. code-block:: bash
+
+        $ pip install sphinx~=1.3.0 git+https://github.com/fabpot/sphinx-php.git
+
+#. Run the following command to build the documentation in HTML format:
+
+   .. code-block:: bash
+
+       # Linux and macOS
+       $ ./_build/make html
+
+       # Windows
+       $ _build\make html
+
+The generated documentation is available in the ``_build/html`` directory.
+
 Frequently Asked Questions
 --------------------------
 
@@ -316,3 +343,7 @@ definitely don't want you to waste your time!
 .. _`sync your fork`: https://help.github.com/articles/syncing-a-fork
 .. _`Platform.sh`: https://platform.sh
 .. _`roadmap`: https://symfony.com/roadmap
+.. _`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