blob: 7ef059e6935d15975b197d1203b3e42523ccb003 [file] [log] [blame]
Gyorgy Szing5e429cb2019-12-03 20:39:55 +01001Building 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
12Prerequisites
13-------------
14
15For building a local copy of the |TFACMF| documentation you will need, at minimum:
16
17- GNUMake
18- Python 3 (3.5 or later)
19- PlantUML (1.2017.15 or later)
20
21You must also install the Python modules that are specified in the
22``requirements.txt`` file in the root of the ``docs`` directory. These modules
23can be installed using ``pip3`` (the Python Package Installer). Passing this
24requirements file as an argument to ``pip3`` automatically installs the specific
25module versions required.
26
27Example environment
28-------------------
29
30An example set of installation commands for Linux with the following assumptions:
31 #. OS and version: Ubuntu 18.04 LTS
32 #. `virtualenv` is used to separate the python dependencies
33 #. pip is used for python dependency management
34 #. `bash` is used as the shell.
35
36.. code:: shell
37
38 sudo apt install make python3 python3-pip virtualenv python3-virtualenv plantuml
39 virtualenv -p python3 ~/tfacmf-venv
40 . ~/tfacmf-venv/bin/activate
41 pip3 install -r requirements.txt
42 deactivate
43
44.. note::
45 More advanced usage instructions for *pip* are beyond the scope of this
46 document but you can refer to the `pip homepage`_ for detailed guides.
47
48.. note::
49 For more information on Virtualenv please refer to the `Virtualenv documentation`_
50
51Building rendered documentation
52-------------------------------
53
54From the ``docs`` directory of the project, run the following commands.
55
56.. code:: shell
57
58 . ~/tfacmf-venv/bin/activate
59 make clean
60 make SPHINXOPTS=-W html
61 deactivate
62
63Output from the build process will be placed in:
64
65::
66
67 <tf-a CMF root>/docs/_build/html/
68
69--------------
70
71.. _Sphinx: http://www.sphinx-doc.org/en/master/
72.. _pip homepage: https://pip.pypa.io/en/stable/
73.. _`Virtualenv documentation`: https://virtualenv.pypa.io/en/latest/
74
75*Copyright (c) 2020, Arm Limited and Contributors. All rights reserved.*
76
77SPDX-License-Identifier: BSD-3-Clause