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 25You must also install the Python modules that are specified in the 26``requirements.txt`` file in the root of the ``docs`` directory. These modules 27can be installed using ``pip3`` (the Python Package Installer). Passing this 28requirements file as an argument to ``pip3`` automatically installs the specific 29module versions required by |TF-A|. 30 31An example set of installation commands for Ubuntu 18.04 LTS follows, assuming 32that the working directory is ``docs``: 33 34.. code:: shell 35 36 sudo apt install python3 python3-pip plantuml 37 pip3 install [--user] -r requirements.txt 38 39.. note:: 40 Several other modules will be installed as dependencies. Please review 41 the list to ensure that there will be no conflicts with other modules already 42 installed in your environment. 43 44Passing the optional ``--user`` argument to ``pip3`` will install the Python 45packages only for the current user. Omitting this argument will attempt to 46install the packages globally and this will likely require the command to be run 47as root or using ``sudo``. 48 49.. note:: 50 More advanced usage instructions for *pip* are beyond the scope of this 51 document but you can refer to the `pip homepage`_ for detailed guides. 52 53Building rendered documentation 54------------------------------- 55 56From the ``docs`` directory of the project, run the following commands. It is 57important to note that you will not get the correct result if the commands are 58run from the project root directory, as that would invoke the top-level Makefile 59for |TF-A| itself. 60 61.. code:: shell 62 63 make clean 64 make html 65 66Output from the build process will be placed in: 67 68:: 69 70 <tf-a root>/docs/build/html/ 71 72-------------- 73 74*Copyright (c) 2019, Arm Limited. All rights reserved.* 75 76.. _Sphinx: http://www.sphinx-doc.org/en/master/ 77.. _pip homepage: https://pip.pypa.io/en/stable/ 78