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 59Documents can be built into HTML-formatted pages from project root directory by 60running the following command. 61 62.. code:: shell 63 64 make doc 65 66Output from the build process will be placed in: 67 68:: 69 70 docs/build/html 71 72We also support building documentation in other formats. From the ``docs`` 73directory of the project, run the following command to see the supported 74formats. It is important to note that you will not get the correct result if 75the command is run from the project root directory, as that would invoke the 76top-level Makefile for |TF-A| itself. 77 78.. code:: shell 79 80 make help 81 82Building rendered documentation from a container 83------------------------------------------------ 84 85There may be cases where you can not either install or upgrade required 86dependencies to generate the documents, so in this case, one way to 87create the documentation is through a docker container. The first step is 88to check if `docker`_ is installed in your host, otherwise check main docker 89page for installation instructions. Once installed, run the following script 90from project root directory 91 92.. code:: shell 93 94 docker run --rm -v $PWD:/TF sphinxdoc/sphinx \ 95 bash -c 'cd /TF && \ 96 pip3 install plantuml -r ./docs/requirements.txt && make doc' 97 98The above command fetches the ``sphinxdoc/sphinx`` container from `docker 99hub`_, launches the container, installs documentation requirements and finally 100creates the documentation. Once done, exit the container and output from the 101build process will be placed in: 102 103:: 104 105 docs/build/html 106 107-------------- 108 109*Copyright (c) 2019, Arm Limited. All rights reserved.* 110 111.. _Sphinx: http://www.sphinx-doc.org/en/master/ 112.. _pip homepage: https://pip.pypa.io/en/stable/ 113.. _Dia: https://wiki.gnome.org/Apps/Dia 114.. _docker: https://www.docker.com/ 115.. _docker hub: https://hub.docker.com/repository/docker/sphinxdoc/sphinx 116