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.5 or later)
23- PlantUML (1.2017.15 or later)
24- Python modules specified in ``docs/requirements.txt``
25
26   You can install these with ``pip3`` (the Python Package Installer) by
27   passing it the requirements file above (with ``-r``). An optional ``--user``
28   argument will install them locally, but you have to add their location to
29   $PATH (pip will emit a warning). Alternatively, they can be installed
30   globally (but will probably require root privileges).
31
32   .. note::
33      Although not necessary, it is recommended you use a virtual environment.
34      More advanced usage instructions for *pip* are beyond the scope of this
35      document but you can refer to the `pip homepage`_ for detailed guides.
36
37- Optionally, the `Dia`_ application can be installed if you need to edit
38  existing ``.dia`` diagram files, or create new ones.
39
40An example set of installation commands for Ubuntu follows, assuming that the
41working directory is ``docs``:
42
43.. code:: shell
44
45    sudo apt install python3 python3-pip plantuml [dia]
46    pip3 install [--user] -r requirements.txt
47
48.. note::
49   Several other modules will be installed as dependencies. Please review
50   the list to ensure that there will be no conflicts with other modules already
51   installed in your environment.
52
53Building rendered documentation
54-------------------------------
55
56Documents can be built into HTML-formatted pages from project root directory by
57running the following command.
58
59.. code:: shell
60
61   make doc
62
63Output from the build process will be placed in:
64
65::
66
67   docs/build/html
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. It is important to note that you will not get the correct result if
72the command is run from the project root directory, as that would invoke the
73top-level Makefile for |TF-A| itself.
74
75.. code:: shell
76
77   make help
78
79Building rendered documentation from a container
80------------------------------------------------
81
82There may be cases where you can not either install or upgrade required
83dependencies to generate the documents, so in this case, one way to
84create the documentation is through a docker container. The first step is
85to check if `docker`_ is installed in your host, otherwise check main docker
86page for installation instructions. Once installed, run the following script
87from project root directory
88
89.. code:: shell
90
91   docker run --rm -v $PWD:/TF sphinxdoc/sphinx \
92          bash -c 'cd /TF && \
93          pip3 install plantuml -r ./docs/requirements.txt && make doc'
94
95The above command fetches the ``sphinxdoc/sphinx`` container from `docker
96hub`_, launches the container, installs documentation requirements and finally
97creates the documentation. Once done, exit the container and output from the
98build process will be placed in:
99
100::
101
102   docs/build/html
103
104--------------
105
106*Copyright (c) 2019, Arm Limited. All rights reserved.*
107
108.. _Sphinx: http://www.sphinx-doc.org/en/master/
109.. _pip homepage: https://pip.pypa.io/en/stable/
110.. _Dia: https://wiki.gnome.org/Apps/Dia
111.. _docker: https://www.docker.com/
112.. _docker hub: https://hub.docker.com/repository/docker/sphinxdoc/sphinx
113