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 poetry run 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 poetry run 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 83The command ``poetry run`` used in the steps above executes the input command 84from inside the project's virtual environment. The easiest way to activate this 85virtual environment is with the ``poetry shell`` command. 86 87Running ``poetry shell`` from the directory containing this project, activates 88the same virtual environment. This creates a sub-shell through which you can 89build the documentation directly with ``make``. 90 91.. code:: shell 92 93 poetry shell 94 make doc 95 96Type ``exit`` to deactivate the virtual environment and exit this new shell. For 97other use cases, please see the official `Poetry`_ documentation. 98 99Building rendered documentation from a container 100------------------------------------------------ 101 102There may be cases where you can not either install or upgrade required 103dependencies to generate the documents, so in this case, one way to 104create the documentation is through a docker container. The first step is 105to check if `docker`_ is installed in your host, otherwise check main docker 106page for installation instructions. Once installed, run the following script 107from project root directory 108 109.. code:: shell 110 111 docker run --rm -v $PWD:/tf-a sphinxdoc/sphinx \ 112 bash -c 'cd /tf-a && 113 apt-get update && apt-get install -y curl plantuml && 114 curl -sSL https://install.python-poetry.org | python3 - && 115 ~/.local/bin/poetry run make doc' 116 117The above command fetches the ``sphinxdoc/sphinx`` container from `docker 118hub`_, launches the container, installs documentation requirements and finally 119creates the documentation. Once done, exit the container and output from the 120build process will be placed in: ``docs/build/html``. 121 122-------------- 123 124*Copyright (c) 2019-2024, Arm Limited. All rights reserved.* 125 126.. _Sphinx: http://www.sphinx-doc.org/en/master/ 127.. _Poetry: https://python-poetry.org/docs/ 128.. _pip homepage: https://pip.pypa.io/en/stable/ 129.. _Dia: https://wiki.gnome.org/Apps/Dia 130.. _docker: https://www.docker.com/ 131.. _docker hub: https://hub.docker.com/repository/docker/sphinxdoc/sphinx 132