docs(build): clarify docs building instructions

Using virtual environments with pip is a generally recommended good
practice but the docs do not acknowledge it. As a result fresh installs
might fail builds due to missing $PATH entries. The Prerequisites
section is also a bit verbose which is difficult to read.

This patch adds the virtual environment mention and clarifies wording.

Signed-off-by: Boyan Karatotev <boyan.karatotev@arm.com>
Change-Id: Iea447fb59dc471a502454650c8548192d93ba879

diff --git a/docs/getting_started/docs-build.rst b/docs/getting_started/docs-build.rst
index 87c677fcded131a74863ffa508d7bd4b3992ff08..64c222e5e86c494d9a3c312c9b2350cf3f91b405 100644 (file)
--- a/docs/getting_started/docs-build.rst
+++ b/docs/getting_started/docs-build.rst
@@ -17,19 +17,25 @@ check that you have the required software packages, as described in the
 Prerequisites
 -------------
 
-For building a local copy of the |TF-A| documentation you will need, at minimum:
+For building a local copy of the |TF-A| documentation you will need:
 
 - Python 3 (3.5 or later)
 - PlantUML (1.2017.15 or later)
+- Python modules specified in ``docs/requirements.txt``
 
-Optionally, the `Dia`_ application can be installed if you need to edit
-existing ``.dia`` diagram files, or create new ones.
+   You can install these with ``pip3`` (the Python Package Installer) by
+   passing it the requirements file above (with ``-r``). An optional ``--user``
+   argument will install them locally, but you have to add their location to
+   $PATH (pip will emit a warning). Alternatively, they can be installed
+   globally (but will probably require root privileges).
 
-You must also install the Python modules that are specified in the
-``requirements.txt`` file in the root of the ``docs`` directory. These modules
-can be installed using ``pip3`` (the Python Package Installer). Passing this
-requirements file as an argument to ``pip3`` automatically installs the specific
-module versions required by |TF-A|.
+   .. note::
+      Although not necessary, it is recommended you use a virtual environment.
+      More advanced usage instructions for *pip* are beyond the scope of this
+      document but you can refer to the `pip homepage`_ for detailed guides.
+
+- Optionally, the `Dia`_ application can be installed if you need to edit
+  existing ``.dia`` diagram files, or create new ones.
 
 An example set of installation commands for Ubuntu 18.04 LTS follows, assuming
 that the working directory is ``docs``:
@@ -44,15 +50,6 @@ that the working directory is ``docs``:
    the list to ensure that there will be no conflicts with other modules already
    installed in your environment.
 
-Passing the optional ``--user`` argument to ``pip3`` will install the Python
-packages only for the current user. Omitting this argument will attempt to
-install the packages globally and this will likely require the command to be run
-as root or using ``sudo``.
-
-.. note::
-   More advanced usage instructions for *pip* are beyond the scope of this
-   document but you can refer to the `pip homepage`_ for detailed guides.
-
 Building rendered documentation
 -------------------------------