diff --git a/contributing/documentation/format.rst b/contributing/documentation/format.rst index 1e224c9f19f..cb4a868e3b5 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 1737b54ab52..b955583121f 100644 --- a/contributing/documentation/overview.rst +++ b/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