From 348b11c8074a0a804b32a2e68937d4f52f09f392 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 3 Aug 2016 12:17:07 +0200 Subject: [PATCH 1/8] Updated the instructions to build docs locally --- contributing/documentation/format.rst | 16 +--------------- contributing/documentation/overview.rst | 18 ++++++++++++++++++ 2 files changed, 19 insertions(+), 15 deletions(-) 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..7163a39e69b 100644 --- a/contributing/documentation/overview.rst +++ b/contributing/documentation/overview.rst @@ -258,6 +258,24 @@ 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 Documentation Locally +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Alternatively you can build the documentation in your own computer following +these steps: + +**Step 1.** Install `pip`_ as explained in the `pip installation`_ article. + +**Step 2.** 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 + +**Step 3.** Run ``make html`` and view the generated documentation in the +``_build/html`` directory. + Frequently Asked Questions -------------------------- From cebc382d8007b705afcdad83d8d12fd36e5a1b73 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 3 Aug 2016 12:43:58 +0200 Subject: [PATCH 2/8] Added the missing link references --- contributing/documentation/overview.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/contributing/documentation/overview.rst b/contributing/documentation/overview.rst index 7163a39e69b..9eb84282aa0 100644 --- a/contributing/documentation/overview.rst +++ b/contributing/documentation/overview.rst @@ -334,3 +334,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 From a7b4d328ca32b21ca1e9044288c2f1b4cc089582 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 3 Aug 2016 17:43:16 +0200 Subject: [PATCH 3/8] Reword the third step --- contributing/documentation/overview.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/contributing/documentation/overview.rst b/contributing/documentation/overview.rst index 9eb84282aa0..80ea4f74ed8 100644 --- a/contributing/documentation/overview.rst +++ b/contributing/documentation/overview.rst @@ -273,8 +273,14 @@ these steps: $ pip install sphinx~=1.3.0 git+https://github.com/fabpot/sphinx-php.git -**Step 3.** Run ``make html`` and view the generated documentation in the -``_build/html`` directory. +**Step 3.** Run the following command to build the documentation in HTML format: + +.. code-block:: bash + + $ cd _build/ + $ make html + +The generated documentation is available in the ``_build/html`` directory. Frequently Asked Questions -------------------------- From c71ad4b78a10331fe143711ad32b8849ac425fca Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 3 Aug 2016 22:03:50 +0200 Subject: [PATCH 4/8] Minor fixes --- contributing/documentation/overview.rst | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/contributing/documentation/overview.rst b/contributing/documentation/overview.rst index 80ea4f74ed8..8c492505cac 100644 --- a/contributing/documentation/overview.rst +++ b/contributing/documentation/overview.rst @@ -258,27 +258,26 @@ 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 Documentation Locally -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Build the Documentation Locally +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Alternatively you can build the documentation in your own computer following these steps: -**Step 1.** Install `pip`_ as explained in the `pip installation`_ article. +1. Install `pip`_ as explained in the `pip installation`_ article. +2. Install `Sphinx`_ and `Sphinx Extensions for PHP and Symfony`_ + (depending on your system, you may need to execute this command as root user): -**Step 2.** 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 -.. code-block:: bash - - $ pip install sphinx~=1.3.0 git+https://github.com/fabpot/sphinx-php.git + $ pip install sphinx~=1.3.0 git+https://github.com/fabpot/sphinx-php.git -**Step 3.** Run the following command to build the documentation in HTML format: +3. Run the following command to build the documentation in HTML format: -.. code-block:: bash + .. code-block:: bash - $ cd _build/ - $ make html + $ cd _build/ + $ make html The generated documentation is available in the ``_build/html`` directory. From 767b49b9b4957eb77be7de0e37d63b65a84ab861 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 3 Aug 2016 22:10:30 +0200 Subject: [PATCH 5/8] Fixed the syntax of the list --- contributing/documentation/overview.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/contributing/documentation/overview.rst b/contributing/documentation/overview.rst index 8c492505cac..e61085577ac 100644 --- a/contributing/documentation/overview.rst +++ b/contributing/documentation/overview.rst @@ -264,15 +264,16 @@ Build the Documentation Locally Alternatively you can build the documentation in your own computer following these steps: -1. Install `pip`_ as explained in the `pip installation`_ article. -2. Install `Sphinx`_ and `Sphinx Extensions for PHP and Symfony`_ +#. 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 -3. Run the following command to build the documentation in HTML format: +#. Run the following command to build the documentation in HTML format: .. code-block:: bash From 77c88bf827cc615d88b3a96290ad471922b37254 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 3 Aug 2016 22:20:47 +0200 Subject: [PATCH 6/8] Fixed again the tricky list syntax --- contributing/documentation/overview.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/contributing/documentation/overview.rst b/contributing/documentation/overview.rst index e61085577ac..8b3874365c4 100644 --- a/contributing/documentation/overview.rst +++ b/contributing/documentation/overview.rst @@ -267,9 +267,9 @@ 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): + (depending on your system, you may need to execute this command as root user): - .. code-block:: bash + .. code-block:: bash $ pip install sphinx~=1.3.0 git+https://github.com/fabpot/sphinx-php.git From 914dd304b89595982113855b2c6417e4fe983c45 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 3 Aug 2016 22:28:58 +0200 Subject: [PATCH 7/8] Fixed the "make" command --- contributing/documentation/overview.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/contributing/documentation/overview.rst b/contributing/documentation/overview.rst index 8b3874365c4..d81c344004f 100644 --- a/contributing/documentation/overview.rst +++ b/contributing/documentation/overview.rst @@ -277,8 +277,7 @@ these steps: .. code-block:: bash - $ cd _build/ - $ make html + $ _build\make html The generated documentation is available in the ``_build/html`` directory. From a2428a4db80d0d7cf9321a1c409e741233dad03f Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 4 Aug 2016 21:40:20 +0200 Subject: [PATCH 8/8] Minor improvements --- contributing/documentation/overview.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/contributing/documentation/overview.rst b/contributing/documentation/overview.rst index d81c344004f..b955583121f 100644 --- a/contributing/documentation/overview.rst +++ b/contributing/documentation/overview.rst @@ -261,8 +261,8 @@ link displayed for Platform.sh service. Build the Documentation Locally ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Alternatively you can build the documentation in your own computer following -these steps: +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. @@ -277,6 +277,10 @@ these steps: .. code-block:: bash + # Linux and macOS + $ ./_build/make html + + # Windows $ _build\make html The generated documentation is available in the ``_build/html`` directory.