2.2. Building Documentation
To create a rendered copy of this documentation locally you can use the Sphinx tool to build and package the plain-text documents into HTML-formatted pages.
If you are building the documentation for the first time then you will need to check that you have the required software packages, as described in the Prerequisites section that follows.
An online copy of the documentation is available at https://www.trustedfirmware.org/docs/tf-a, if you want to view a rendered copy without doing a local build.
For building a local copy of the TF-A documentation you will need:
Python 3 (3.8 or later)
PlantUML (1.2017.15 or later)
Poetry (Python dependency manager)
Optionally, the Dia application can be installed if you need to edit existing
.diadiagram files, or create new ones.
Below is an example set of instructions to get a working environment (tested on Ubuntu):
sudo apt install python3 python3-pip plantuml [dia] curl -sSL https://install.python-poetry.org | python3 -
2.2.2. Building rendered documentation
To install Python dependencies using Poetry:
Poetry will create a new virtual environment and install all dependencies listed
pyproject.toml. You can get information about this environment, such as
its location and the Python version, with the command:
poetry env info
If you have already sourced a virtual environment, Poetry will respect this and install dependencies there.
Once all dependencies are installed, the documentation can be compiled into HTML-formatted pages from the project root directory by running:
poetry run make doc
Output from the build process will be placed in:
220.127.116.11. Other Output Formats
We also support building documentation in other formats. From the
directory of the project, run the following command to see the supported
poetry run make -C docs help
To build the documentation in PDF format, additionally ensure that the following packages are installed:
Below is an example set of instructions to install the required packages (tested on Ubuntu):
sudo apt install fonts-freefont-otf latexmk librsvg2-bin texlive-xetex xindy
Once all the dependencies are installed, run the command
poetry run make -C
docs latexpdf to build the documentation. Output from the build process
trustedfirmware-a.pdf) can be found in
18.104.22.168. Building rendered documentation from Poetry’s virtual environment
poetry run used in the steps above executes the input command
from inside the project’s virtual environment. The easiest way to activate this
virtual environment is with the
poetry shell command.
poetry shell from the directory containing this project, activates
the same virtual environment. This creates a sub-shell through which you can
build the documentation directly with
poetry shell make doc
exit to deactivate the virtual environment and exit this new shell. For
other use cases, please see the official Poetry documentation.
2.2.3. Building rendered documentation from a container
There may be cases where you can not either install or upgrade required dependencies to generate the documents, so in this case, one way to create the documentation is through a docker container. The first step is to check if docker is installed in your host, otherwise check main docker page for installation instructions. Once installed, run the following script from project root directory
docker run --rm -v $PWD:/tf-a sphinxdoc/sphinx \ bash -c 'cd /tf-a && apt-get update && apt-get install -y curl plantuml && curl -sSL https://install.python-poetry.org | python3 - && ~/.local/bin/poetry install && ~/.local/bin/poetry run make doc'
The above command fetches the
sphinxdoc/sphinx container from docker
hub, launches the container, installs documentation requirements and finally
creates the documentation. Once done, exit the container and output from the
build process will be placed in:
Copyright (c) 2019-2023, Arm Limited. All rights reserved.