1Building Documentation
2======================
3
4To create a rendered copy of this documentation locally you can use the
5`Sphinx`_ tool to build and package the plain-text documents into HTML-formatted
6pages.
7
8If you are building the documentation for the first time then you will need to
9check that you have the required software packages, as described in the
10*Prerequisites* section that follows.
11
12.. note::
13   An online copy of the documentation is available at
14   https://www.trustedfirmware.org/docs/tf-a, if you want to view a rendered
15   copy without doing a local build.
16
17Prerequisites
18-------------
19
20For building a local copy of the |TF-A| documentation you will need:
21
22- Python 3 (3.8 or later)
23- PlantUML (1.2017.15 or later)
24- `Poetry`_ (Python dependency manager)
25- Optionally, the `Dia`_ application can be installed if you need to edit
26  existing ``.dia`` diagram files, or create new ones.
27
28
29Below is an example set of instructions to get a working environment (tested on
30Ubuntu):
31
32.. code:: shell
33
34    sudo apt install python3 python3-pip plantuml [dia]
35    curl -sSL https://install.python-poetry.org | python3 -
36
37Building rendered documentation
38-------------------------------
39
40To install Python dependencies using Poetry:
41
42.. code:: shell
43
44    poetry install
45
46Poetry will create a new virtual environment and install all dependencies listed
47in ``pyproject.toml``. You can get information about this environment, such as
48its location and the Python version, with the command:
49
50.. code:: shell
51
52    poetry env info
53
54If you have already sourced a virtual environment, Poetry will respect this and
55install dependencies there.
56
57Once all dependencies are installed, the documentation can be compiled into
58HTML-formatted pages from the project root directory by running:
59
60.. code:: shell
61
62   poetry run make doc
63
64Output from the build process will be placed in: ``docs/build/html``.
65
66Other Output Formats
67~~~~~~~~~~~~~~~~~~~~
68
69We also support building documentation in other formats. From the ``docs``
70directory of the project, run the following command to see the supported
71formats.
72
73.. code:: shell
74
75   poetry run make -C docs help
76
77To build the documentation in PDF format, additionally ensure that the following
78packages are installed:
79
80- FreeSerif font
81- latexmk
82- librsvg2-bin
83- xelatex
84- xindy
85
86Below is an example set of instructions to install the required packages
87(tested on Ubuntu):
88
89.. code:: shell
90
91	sudo apt install fonts-freefont-otf latexmk librsvg2-bin texlive-xetex xindy
92
93Once all the dependencies are installed, run the command ``poetry run make -C
94docs latexpdf`` to build the documentation. Output from the build process
95(``trustedfirmware-a.pdf``) can be found in ``docs/build/latex``.
96
97Building rendered documentation from Poetry's virtual environment
98~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
99
100The command ``poetry run`` used in the steps above executes the input command
101from inside the project's virtual environment. The easiest way to activate this
102virtual environment is with the ``poetry shell`` command.
103
104Running ``poetry shell`` from the directory containing this project, activates
105the same virtual environment. This creates a sub-shell through which you can
106build the documentation directly with ``make``.
107
108.. code:: shell
109
110    poetry shell
111    make doc
112
113Type ``exit`` to deactivate the virtual environment and exit this new shell. For
114other use cases, please see the official `Poetry`_ documentation.
115
116Building rendered documentation from a container
117------------------------------------------------
118
119There may be cases where you can not either install or upgrade required
120dependencies to generate the documents, so in this case, one way to
121create the documentation is through a docker container. The first step is
122to check if `docker`_ is installed in your host, otherwise check main docker
123page for installation instructions. Once installed, run the following script
124from project root directory
125
126.. code:: shell
127
128   docker run --rm -v $PWD:/tf-a sphinxdoc/sphinx \
129        bash -c 'cd /tf-a &&
130            apt-get update && apt-get install -y curl plantuml &&
131            curl -sSL https://install.python-poetry.org | python3 - &&
132            ~/.local/bin/poetry install && ~/.local/bin/poetry run make doc'
133
134The above command fetches the ``sphinxdoc/sphinx`` container from `docker
135hub`_, launches the container, installs documentation requirements and finally
136creates the documentation. Once done, exit the container and output from the
137build process will be placed in: ``docs/build/html``.
138
139--------------
140
141*Copyright (c) 2019-2023, Arm Limited. All rights reserved.*
142
143.. _Sphinx: http://www.sphinx-doc.org/en/master/
144.. _Poetry: https://python-poetry.org/docs/
145.. _pip homepage: https://pip.pypa.io/en/stable/
146.. _Dia: https://wiki.gnome.org/Apps/Dia
147.. _docker: https://www.docker.com/
148.. _docker hub: https://hub.docker.com/repository/docker/sphinxdoc/sphinx
149