1862c764aSPaul BeesleyBuilding Documentation 2862c764aSPaul Beesley====================== 3862c764aSPaul Beesley 4862c764aSPaul BeesleyTo create a rendered copy of this documentation locally you can use the 5862c764aSPaul Beesley`Sphinx`_ tool to build and package the plain-text documents into HTML-formatted 6862c764aSPaul Beesleypages. 7862c764aSPaul Beesley 8862c764aSPaul BeesleyIf you are building the documentation for the first time then you will need to 9862c764aSPaul Beesleycheck that you have the required software packages, as described in the 10862c764aSPaul Beesley*Prerequisites* section that follows. 11862c764aSPaul Beesley 12862c764aSPaul Beesley.. note:: 13862c764aSPaul Beesley An online copy of the documentation is available at 14862c764aSPaul Beesley https://www.trustedfirmware.org/docs/tf-a, if you want to view a rendered 15862c764aSPaul Beesley copy without doing a local build. 16862c764aSPaul Beesley 17862c764aSPaul BeesleyPrerequisites 18862c764aSPaul Beesley------------- 19862c764aSPaul Beesley 20862c764aSPaul BeesleyFor building a local copy of the |TF-A| documentation you will need, at minimum: 21862c764aSPaul Beesley 22862c764aSPaul Beesley- Python 3 (3.5 or later) 23862c764aSPaul Beesley- PlantUML (1.2017.15 or later) 24862c764aSPaul Beesley 2543f35ef5SPaul BeesleyOptionally, the `Dia`_ application can be installed if you need to edit 2643f35ef5SPaul Beesleyexisting ``.dia`` diagram files, or create new ones. 2743f35ef5SPaul Beesley 28862c764aSPaul BeesleyYou must also install the Python modules that are specified in the 29862c764aSPaul Beesley``requirements.txt`` file in the root of the ``docs`` directory. These modules 30862c764aSPaul Beesleycan be installed using ``pip3`` (the Python Package Installer). Passing this 31862c764aSPaul Beesleyrequirements file as an argument to ``pip3`` automatically installs the specific 32862c764aSPaul Beesleymodule versions required by |TF-A|. 33862c764aSPaul Beesley 34862c764aSPaul BeesleyAn example set of installation commands for Ubuntu 18.04 LTS follows, assuming 35862c764aSPaul Beesleythat the working directory is ``docs``: 36862c764aSPaul Beesley 37862c764aSPaul Beesley.. code:: shell 38862c764aSPaul Beesley 3943f35ef5SPaul Beesley sudo apt install python3 python3-pip plantuml [dia] 40862c764aSPaul Beesley pip3 install [--user] -r requirements.txt 41862c764aSPaul Beesley 42862c764aSPaul Beesley.. note:: 43862c764aSPaul Beesley Several other modules will be installed as dependencies. Please review 44862c764aSPaul Beesley the list to ensure that there will be no conflicts with other modules already 45862c764aSPaul Beesley installed in your environment. 46862c764aSPaul Beesley 47862c764aSPaul BeesleyPassing the optional ``--user`` argument to ``pip3`` will install the Python 48862c764aSPaul Beesleypackages only for the current user. Omitting this argument will attempt to 49862c764aSPaul Beesleyinstall the packages globally and this will likely require the command to be run 50862c764aSPaul Beesleyas root or using ``sudo``. 51862c764aSPaul Beesley 52862c764aSPaul Beesley.. note:: 53862c764aSPaul Beesley More advanced usage instructions for *pip* are beyond the scope of this 54862c764aSPaul Beesley document but you can refer to the `pip homepage`_ for detailed guides. 55862c764aSPaul Beesley 56862c764aSPaul BeesleyBuilding rendered documentation 57862c764aSPaul Beesley------------------------------- 58862c764aSPaul Beesley 59*6de32378SMadhukar PappireddyDocuments can be built into HTML-formatted pages from project root directory by 60*6de32378SMadhukar Pappireddyrunning the following command. 61862c764aSPaul Beesley 62862c764aSPaul Beesley.. code:: shell 63862c764aSPaul Beesley 64*6de32378SMadhukar Pappireddy make doc 65862c764aSPaul Beesley 66862c764aSPaul BeesleyOutput from the build process will be placed in: 67862c764aSPaul Beesley 68862c764aSPaul Beesley:: 69862c764aSPaul Beesley 70*6de32378SMadhukar Pappireddy docs/build/html/ 71*6de32378SMadhukar Pappireddy 72*6de32378SMadhukar PappireddyWe also support building documentation in other formats. From the ``docs`` 73*6de32378SMadhukar Pappireddydirectory of the project, run the following command to see the supported 74*6de32378SMadhukar Pappireddyformats. It is important to note that you will not get the correct result if 75*6de32378SMadhukar Pappireddythe command is run from the project root directory, as that would invoke the 76*6de32378SMadhukar Pappireddytop-level Makefile for |TF-A| itself. 77*6de32378SMadhukar Pappireddy 78*6de32378SMadhukar Pappireddy.. code:: shell 79*6de32378SMadhukar Pappireddy 80*6de32378SMadhukar Pappireddy make help 81862c764aSPaul Beesley 82862c764aSPaul Beesley-------------- 83862c764aSPaul Beesley 84862c764aSPaul Beesley*Copyright (c) 2019, Arm Limited. All rights reserved.* 85862c764aSPaul Beesley 86862c764aSPaul Beesley.. _Sphinx: http://www.sphinx-doc.org/en/master/ 87862c764aSPaul Beesley.. _pip homepage: https://pip.pypa.io/en/stable/ 8843f35ef5SPaul Beesley.. _Dia: https://wiki.gnome.org/Apps/Dia 89