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 59From the ``docs`` directory of the project, run the following commands. It is 60important to note that you will not get the correct result if the commands are 61run from the project root directory, as that would invoke the top-level Makefile 62for |TF-A| itself. 63 64.. code:: shell 65 66 make clean 67 make html 68 69Output from the build process will be placed in: 70 71:: 72 73 <tf-a root>/docs/build/html/ 74 75-------------- 76 77*Copyright (c) 2019, Arm Limited. All rights reserved.* 78 79.. _Sphinx: http://www.sphinx-doc.org/en/master/ 80.. _pip homepage: https://pip.pypa.io/en/stable/ 81.. _Dia: https://wiki.gnome.org/Apps/Dia 82