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: 21 22- Python 3 (3.8 or later) 23- PlantUML (1.2017.15 or later) 24- Poetry Python dependency and package manager 25- Python modules specified in ``pyproject.toml`` 26- Optionally, the `Dia`_ application can be installed if you need to edit 27 existing ``.dia`` diagram files, or create new ones. 28 29 30Poetry will handle the creation of a virtual build environment, either creating 31a new environment or re-using one created by the user, and installing all 32dependencies herein. This ensures that the Python environment is isolated from 33your system environment. 34 35An example set of installation commands for Ubuntu follows: 36 37.. code:: shell 38 39 sudo apt install python3 python3-pip plantuml [dia] 40 curl -sSL https://install.python-poetry.org | python3 - 41 poetry install 42 43Building rendered documentation 44------------------------------- 45 46Documents can be built into HTML-formatted pages from project root directory by 47running the following command. 48 49.. code:: shell 50 51 poetry run make doc 52 53Output from the build process will be placed in: 54 55:: 56 57 docs/build/html 58 59We also support building documentation in other formats. From the ``docs`` 60directory of the project, run the following command to see the supported 61formats. It is important to note that you will not get the correct result if 62the command is run from the project root directory, as that would invoke the 63top-level Makefile for |TF-A| itself. 64 65.. code:: shell 66 67 poetry run make help 68 69.. note:: 70 71 The ``run`` command used above executes ``make`` in the projects virtual 72 environment. To spawn a shell in this environment, use ``poetry 73 shell``. For other use cases, please see the official `Poetry`_ 74 documentation. 75 76Building rendered documentation from a container 77------------------------------------------------ 78 79There may be cases where you can not either install or upgrade required 80dependencies to generate the documents, so in this case, one way to 81create the documentation is through a docker container. The first step is 82to check if `docker`_ is installed in your host, otherwise check main docker 83page for installation instructions. Once installed, run the following script 84from project root directory 85 86.. code:: shell 87 88 docker run --rm -v $PWD:/TF sphinxdoc/sphinx \ 89 bash -c 'cd /TF && \ 90 poetry install && poetry run make doc' 91 92The above command fetches the ``sphinxdoc/sphinx`` container from `docker 93hub`_, launches the container, installs documentation requirements and finally 94creates the documentation. Once done, exit the container and output from the 95build process will be placed in: 96 97:: 98 99 docs/build/html 100 101-------------- 102 103*Copyright (c) 2019-2023, Arm Limited. All rights reserved.* 104 105.. _Sphinx: http://www.sphinx-doc.org/en/master/ 106.. _Poetry: https://python-poetry.org/docs/cli/ 107.. _pip homepage: https://pip.pypa.io/en/stable/ 108.. _Dia: https://wiki.gnome.org/Apps/Dia 109.. _docker: https://www.docker.com/ 110.. _docker hub: https://hub.docker.com/repository/docker/sphinxdoc/sphinx 111