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