minor symfony#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 symfony#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