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 40To install Python dependencies using Poetry: 41 42.. code:: shell 43 44 poetry install 45 46Poetry will create a new virtual environment and install all dependencies listed 47in ``pyproject.toml``. You can get information about this environment, such as 48its location and the Python version, with the command: 49 50.. code:: shell 51 52 poetry env info 53 54If you have already sourced a virtual environment, Poetry will respect this and 55install dependencies there. 56 57Once all dependencies are installed, the documentation can be compiled into 58HTML-formatted pages from the project root directory by running: 59 60.. code:: shell 61 62 poetry run make doc 63 64Output from the build process will be placed in: ``docs/build/html``. 65 66Other Output Formats 67~~~~~~~~~~~~~~~~~~~~ 68 69We also support building documentation in other formats. From the ``docs`` 70directory of the project, run the following command to see the supported 71formats. 72 73.. code:: shell 74 75 poetry run make -C docs help 76 77Building rendered documentation from Poetry's virtual environment 78~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 79 80The command ``poetry run`` used in the steps above executes the input command 81from inside the project's virtual environment. The easiest way to activate this 82virtual environment is with the ``poetry shell`` command. 83 84Running ``poetry shell`` from the directory containing this project, activates 85the same virtual environment. This creates a sub-shell through which you can 86build the documentation directly with ``make``. 87 88.. code:: shell 89 90 poetry shell 91 make doc 92 93Type ``exit`` to deactivate the virtual environment and exit this new shell. For 94other use cases, please see the official `Poetry`_ documentation. 95 96Building rendered documentation from a container 97------------------------------------------------ 98 99There may be cases where you can not either install or upgrade required 100dependencies to generate the documents, so in this case, one way to 101create the documentation is through a docker container. The first step is 102to check if `docker`_ is installed in your host, otherwise check main docker 103page for installation instructions. Once installed, run the following script 104from project root directory 105 106.. code:: shell 107 108 docker run --rm -v $PWD:/tf-a sphinxdoc/sphinx \ 109 bash -c 'cd /tf-a && 110 apt-get update && apt-get install -y curl plantuml && 111 curl -sSL https://install.python-poetry.org | python3 - && 112 ~/.local/bin/poetry install && ~/.local/bin/poetry run make doc' 113 114The above command fetches the ``sphinxdoc/sphinx`` container from `docker 115hub`_, launches the container, installs documentation requirements and finally 116creates the documentation. Once done, exit the container and output from the 117build process will be placed in: ``docs/build/html``. 118 119-------------- 120 121*Copyright (c) 2019-2023, Arm Limited. All rights reserved.* 122 123.. _Sphinx: http://www.sphinx-doc.org/en/master/ 124.. _Poetry: https://python-poetry.org/docs/ 125.. _pip homepage: https://pip.pypa.io/en/stable/ 126.. _Dia: https://wiki.gnome.org/Apps/Dia 127.. _docker: https://www.docker.com/ 128.. _docker hub: https://hub.docker.com/repository/docker/sphinxdoc/sphinx 129