From: Boyan Karatotev Date: Thu, 27 Oct 2022 12:55:12 +0000 (+0100) Subject: docs(build): clarify docs building instructions X-Git-Tag: baikal/aarch64/sdk5.9~9^2~2 X-Git-Url: https://git.baikalelectronics.ru/?a=commitdiff_plain;h=8526472a46886f0a50c099ef17a1bf8add69ac06;p=arm-tf.git 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 Change-Id: Iea447fb59dc471a502454650c8548192d93ba879 --- diff --git a/docs/getting_started/docs-build.rst b/docs/getting_started/docs-build.rst index 87c677fcd..64c222e5e 100644 --- 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 -------------------------------