blob: 87c677fcded131a74863ffa508d7bd4b3992ff08 [file] [log] [blame]
Paul Beesley5d3799b2019-10-07 10:04:48 +00001Building 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
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +010025Optionally, the `Dia`_ application can be installed if you need to edit
26existing ``.dia`` diagram files, or create new ones.
27
Paul Beesley5d3799b2019-10-07 10:04:48 +000028You 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
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +010039 sudo apt install python3 python3-pip plantuml [dia]
Paul Beesley5d3799b2019-10-07 10:04:48 +000040 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
Madhukar Pappireddy46adb1b2020-01-28 12:41:20 -060059Documents can be built into HTML-formatted pages from project root directory by
60running the following command.
Paul Beesley5d3799b2019-10-07 10:04:48 +000061
62.. code:: shell
63
Madhukar Pappireddy46adb1b2020-01-28 12:41:20 -060064 make doc
Paul Beesley5d3799b2019-10-07 10:04:48 +000065
66Output from the build process will be placed in:
67
68::
69
Leonardo Sandoval8f9f6882020-06-10 18:26:28 -050070 docs/build/html
Madhukar Pappireddy46adb1b2020-01-28 12:41:20 -060071
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
Paul Beesley5d3799b2019-10-07 10:04:48 +000081
Leonardo Sandoval8f9f6882020-06-10 18:26:28 -050082Building 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
Paul Beesley5d3799b2019-10-07 10:04:48 +0000107--------------
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/
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +0100113.. _Dia: https://wiki.gnome.org/Apps/Dia
Leonardo Sandoval8f9f6882020-06-10 18:26:28 -0500114.. _docker: https://www.docker.com/
115.. _docker hub: https://hub.docker.com/repository/docker/sphinxdoc/sphinx