Merge changes If90a18ee,I02e88f8c,Iea447fb5,Ie0570481,Ieeb14cfc into integration

* changes:
  docs: add top level section numbering
  docs(build): clarify getting started section
  docs(build): clarify docs building instructions
  fix(docs): prevent a sphinx warning
  fix(docs): prevent a virtual environment from failing a build

diff --cc docs/getting_started/docs-build.rst
index 1762558a5e1739df0c3aee549a8d2a55537853a4,64c222e5e86c494d9a3c312c9b2350cf3f91b405..4a480590bc6167b8883e92c4f6074b6e26e101bd
--- 1/docs/getting_started/docs-build.rst
--- 2/docs/getting_started/docs-build.rst
+++ b/docs/getting_started/docs-build.rst
@@@ -21,18 -21,24 +21,24 @@@ For building a local copy of the |TF-A
  
  - 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``:
 +An example set of installation commands for Ubuntu follows, assuming that the
 +working directory is ``docs``:
  
  .. code:: shell
  

diff --cc docs/getting_started/prerequisites.rst
Simple merge