From: Manish V Badarkhe <manish.badarkhe@arm.com>
Date: Wed, 16 Nov 2022 15:18:54 +0000 (+0100)
Subject: Merge changes If90a18ee,I02e88f8c,Iea447fb5,Ie0570481,Ieeb14cfc into integration
X-Git-Tag: baikal/aarch64/sdk5.9~9
X-Git-Url: https://git.baikalelectronics.ru/?a=commitdiff_plain;h=71061819aaf1b69c8600e1b7d9c9388b8f51b680;p=arm-tf.git

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
---

71061819aaf1b69c8600e1b7d9c9388b8f51b680
diff --cc docs/getting_started/docs-build.rst
index 1762558a5,64c222e5e..4a480590b
--- a/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