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 manager) 25- Optionally, the `Dia`_ application can be installed if you need to edit 26 existing ``.dia`` diagram files, or create new ones. 27 28 29Below is an example set of instructions to get a working environment (tested on 30Ubuntu): 31 32.. code:: shell 33 34 sudo apt install python3 python3-pip plantuml [dia] 35 curl -sSL https://install.python-poetry.org | python3 - 36 37Building rendered documentation 38------------------------------- 39 40The documentation can be compiled into HTML-formatted pages from the project 41root directory by running: 42 43.. code:: shell 44 45 make doc 46 47Output from the build process will be placed in: ``docs/build/html``. 48 49Other Output Formats 50~~~~~~~~~~~~~~~~~~~~ 51 52We also support building documentation in other formats. From the ``docs`` 53directory of the project, run the following command to see the supported 54formats. 55 56.. code:: shell 57 58 make -C docs help 59 60To build the documentation in PDF format, additionally ensure that the following 61packages are installed: 62 63- FreeSerif font 64- latexmk 65- librsvg2-bin 66- xelatex 67- xindy 68 69Below is an example set of instructions to install the required packages 70(tested on Ubuntu): 71 72.. code:: shell 73 74 sudo apt install fonts-freefont-otf latexmk librsvg2-bin texlive-xetex xindy 75 76Once all the dependencies are installed, run the command ``poetry run make -C 77docs latexpdf`` to build the documentation. Output from the build process 78(``trustedfirmware-a.pdf``) can be found in ``docs/build/latex``. 79 80Building rendered documentation from Poetry's virtual environment 81~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 82 83If Poetry is installed, the ``doc`` target wraps its build steps with ``poetry 84run``, which runs the specified command within the project's virtual 85environment. The easiest way to activate this environment manually is by using 86the ``poetry shell`` command. 87 88Running ``poetry shell`` from the directory containing this project, activates 89the same virtual environment. This creates a sub-shell through which you can 90build the documentation directly with ``make``. 91 92.. code:: shell 93 94 poetry shell 95 make -C docs html 96 97Type ``exit`` to deactivate the virtual environment and exit this new shell. For 98other use cases, please see the official `Poetry`_ documentation. 99 100Building rendered documentation from a container 101------------------------------------------------ 102 103There may be cases where you can not either install or upgrade required 104dependencies to generate the documents, so in this case, one way to 105create the documentation is through a docker container. The first step is 106to check if `docker`_ is installed in your host, otherwise check main docker 107page for installation instructions. Once installed, run the following script 108from project root directory 109 110.. code:: shell 111 112 docker run --rm -v $PWD:/tf-a sphinxdoc/sphinx \ 113 bash -c 'cd /tf-a && 114 apt-get update && apt-get install -y curl plantuml && 115 curl -sSL https://install.python-poetry.org | python3 - && 116 ~/.local/bin/poetry run make doc' 117 118The above command fetches the ``sphinxdoc/sphinx`` container from `docker 119hub`_, launches the container, installs documentation requirements and finally 120creates the documentation. Once done, exit the container and output from the 121build process will be placed in: ``docs/build/html``. 122 123-------------- 124 125*Copyright (c) 2019-2025, Arm Limited. All rights reserved.* 126 127.. _Sphinx: http://www.sphinx-doc.org/en/master/ 128.. _Poetry: https://python-poetry.org/docs/ 129.. _pip homepage: https://pip.pypa.io/en/stable/ 130.. _Dia: https://wiki.gnome.org/Apps/Dia 131.. _docker: https://www.docker.com/ 132.. _docker hub: https://hub.docker.com/repository/docker/sphinxdoc/sphinx 133