1*54fd6939SJiyong ParkBuilding Documentation 2*54fd6939SJiyong Park====================== 3*54fd6939SJiyong Park 4*54fd6939SJiyong ParkTo create a rendered copy of this documentation locally you can use the 5*54fd6939SJiyong Park`Sphinx`_ tool to build and package the plain-text documents into HTML-formatted 6*54fd6939SJiyong Parkpages. 7*54fd6939SJiyong Park 8*54fd6939SJiyong ParkIf you are building the documentation for the first time then you will need to 9*54fd6939SJiyong Parkcheck that you have the required software packages, as described in the 10*54fd6939SJiyong Park*Prerequisites* section that follows. 11*54fd6939SJiyong Park 12*54fd6939SJiyong Park.. note:: 13*54fd6939SJiyong Park An online copy of the documentation is available at 14*54fd6939SJiyong Park https://www.trustedfirmware.org/docs/tf-a, if you want to view a rendered 15*54fd6939SJiyong Park copy without doing a local build. 16*54fd6939SJiyong Park 17*54fd6939SJiyong ParkPrerequisites 18*54fd6939SJiyong Park------------- 19*54fd6939SJiyong Park 20*54fd6939SJiyong ParkFor building a local copy of the |TF-A| documentation you will need, at minimum: 21*54fd6939SJiyong Park 22*54fd6939SJiyong Park- Python 3 (3.5 or later) 23*54fd6939SJiyong Park- PlantUML (1.2017.15 or later) 24*54fd6939SJiyong Park 25*54fd6939SJiyong ParkOptionally, the `Dia`_ application can be installed if you need to edit 26*54fd6939SJiyong Parkexisting ``.dia`` diagram files, or create new ones. 27*54fd6939SJiyong Park 28*54fd6939SJiyong ParkYou must also install the Python modules that are specified in the 29*54fd6939SJiyong Park``requirements.txt`` file in the root of the ``docs`` directory. These modules 30*54fd6939SJiyong Parkcan be installed using ``pip3`` (the Python Package Installer). Passing this 31*54fd6939SJiyong Parkrequirements file as an argument to ``pip3`` automatically installs the specific 32*54fd6939SJiyong Parkmodule versions required by |TF-A|. 33*54fd6939SJiyong Park 34*54fd6939SJiyong ParkAn example set of installation commands for Ubuntu 18.04 LTS follows, assuming 35*54fd6939SJiyong Parkthat the working directory is ``docs``: 36*54fd6939SJiyong Park 37*54fd6939SJiyong Park.. code:: shell 38*54fd6939SJiyong Park 39*54fd6939SJiyong Park sudo apt install python3 python3-pip plantuml [dia] 40*54fd6939SJiyong Park pip3 install [--user] -r requirements.txt 41*54fd6939SJiyong Park 42*54fd6939SJiyong Park.. note:: 43*54fd6939SJiyong Park Several other modules will be installed as dependencies. Please review 44*54fd6939SJiyong Park the list to ensure that there will be no conflicts with other modules already 45*54fd6939SJiyong Park installed in your environment. 46*54fd6939SJiyong Park 47*54fd6939SJiyong ParkPassing the optional ``--user`` argument to ``pip3`` will install the Python 48*54fd6939SJiyong Parkpackages only for the current user. Omitting this argument will attempt to 49*54fd6939SJiyong Parkinstall the packages globally and this will likely require the command to be run 50*54fd6939SJiyong Parkas root or using ``sudo``. 51*54fd6939SJiyong Park 52*54fd6939SJiyong Park.. note:: 53*54fd6939SJiyong Park More advanced usage instructions for *pip* are beyond the scope of this 54*54fd6939SJiyong Park document but you can refer to the `pip homepage`_ for detailed guides. 55*54fd6939SJiyong Park 56*54fd6939SJiyong ParkBuilding rendered documentation 57*54fd6939SJiyong Park------------------------------- 58*54fd6939SJiyong Park 59*54fd6939SJiyong ParkDocuments can be built into HTML-formatted pages from project root directory by 60*54fd6939SJiyong Parkrunning the following command. 61*54fd6939SJiyong Park 62*54fd6939SJiyong Park.. code:: shell 63*54fd6939SJiyong Park 64*54fd6939SJiyong Park make doc 65*54fd6939SJiyong Park 66*54fd6939SJiyong ParkOutput from the build process will be placed in: 67*54fd6939SJiyong Park 68*54fd6939SJiyong Park:: 69*54fd6939SJiyong Park 70*54fd6939SJiyong Park docs/build/html 71*54fd6939SJiyong Park 72*54fd6939SJiyong ParkWe also support building documentation in other formats. From the ``docs`` 73*54fd6939SJiyong Parkdirectory of the project, run the following command to see the supported 74*54fd6939SJiyong Parkformats. It is important to note that you will not get the correct result if 75*54fd6939SJiyong Parkthe command is run from the project root directory, as that would invoke the 76*54fd6939SJiyong Parktop-level Makefile for |TF-A| itself. 77*54fd6939SJiyong Park 78*54fd6939SJiyong Park.. code:: shell 79*54fd6939SJiyong Park 80*54fd6939SJiyong Park make help 81*54fd6939SJiyong Park 82*54fd6939SJiyong ParkBuilding rendered documentation from a container 83*54fd6939SJiyong Park------------------------------------------------ 84*54fd6939SJiyong Park 85*54fd6939SJiyong ParkThere may be cases where you can not either install or upgrade required 86*54fd6939SJiyong Parkdependencies to generate the documents, so in this case, one way to 87*54fd6939SJiyong Parkcreate the documentation is through a docker container. The first step is 88*54fd6939SJiyong Parkto check if `docker`_ is installed in your host, otherwise check main docker 89*54fd6939SJiyong Parkpage for installation instructions. Once installed, run the following script 90*54fd6939SJiyong Parkfrom project root directory 91*54fd6939SJiyong Park 92*54fd6939SJiyong Park.. code:: shell 93*54fd6939SJiyong Park 94*54fd6939SJiyong Park docker run --rm -v $PWD:/TF sphinxdoc/sphinx \ 95*54fd6939SJiyong Park bash -c 'cd /TF && \ 96*54fd6939SJiyong Park pip3 install plantuml -r ./docs/requirements.txt && make doc' 97*54fd6939SJiyong Park 98*54fd6939SJiyong ParkThe above command fetches the ``sphinxdoc/sphinx`` container from `docker 99*54fd6939SJiyong Parkhub`_, launches the container, installs documentation requirements and finally 100*54fd6939SJiyong Parkcreates the documentation. Once done, exit the container and output from the 101*54fd6939SJiyong Parkbuild process will be placed in: 102*54fd6939SJiyong Park 103*54fd6939SJiyong Park:: 104*54fd6939SJiyong Park 105*54fd6939SJiyong Park docs/build/html 106*54fd6939SJiyong Park 107*54fd6939SJiyong Park-------------- 108*54fd6939SJiyong Park 109*54fd6939SJiyong Park*Copyright (c) 2019, Arm Limited. All rights reserved.* 110*54fd6939SJiyong Park 111*54fd6939SJiyong Park.. _Sphinx: http://www.sphinx-doc.org/en/master/ 112*54fd6939SJiyong Park.. _pip homepage: https://pip.pypa.io/en/stable/ 113*54fd6939SJiyong Park.. _Dia: https://wiki.gnome.org/Apps/Dia 114*54fd6939SJiyong Park.. _docker: https://www.docker.com/ 115*54fd6939SJiyong Park.. _docker hub: https://hub.docker.com/repository/docker/sphinxdoc/sphinx 116