Djam/arm-trusted-firmware
1
0
Fork 0
mirror of https://github.com/ARM-software/arm-trusted-firmware.git synced 2025-04-19 02:54:24 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs(build): clarify docs building instructions

Browse source 
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
This commit is contained in:
Boyan Karatotev 2022-10-27 13:55:12 +01:00
parent e48b1f8c48
commit 8526472a46
1 changed files with 14 additions and 17 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

31
docs/getting_started/docs-build.rst
View file

@ -17,19 +17,25 @@ check that you have the required software packages, as described in the
Prerequisites 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) - Python 3 (3.5 or later)
- PlantUML (1.2017.15 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 You can install these with ``pip3`` (the Python Package Installer) by
existing ``.dia`` diagram files, or create new ones. 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 .. note::
``requirements.txt`` file in the root of the ``docs`` directory. These modules Although not necessary, it is recommended you use a virtual environment.
can be installed using ``pip3`` (the Python Package Installer). Passing this More advanced usage instructions for *pip* are beyond the scope of this
requirements file as an argument to ``pip3`` automatically installs the specific document but you can refer to the `pip homepage`_ for detailed guides.
module versions required by |TF-A|.
- 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 An example set of installation commands for Ubuntu 18.04 LTS follows, assuming
that the working directory is ``docs``: 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 the list to ensure that there will be no conflicts with other modules already
installed in your environment. 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 Building rendered documentation
------------------------------- -------------------------------