diff options
Diffstat (limited to '')
| -rw-r--r-- | docs/getting_started/docs-build.rst | 148 |
1 files changed, 148 insertions, 0 deletions
diff --git a/docs/getting_started/docs-build.rst b/docs/getting_started/docs-build.rst new file mode 100644 index 0000000..50fff57 --- /dev/null +++ b/docs/getting_started/docs-build.rst @@ -0,0 +1,148 @@ +Building Documentation +====================== + +To create a rendered copy of this documentation locally you can use the +`Sphinx`_ tool to build and package the plain-text documents into HTML-formatted +pages. + +If you are building the documentation for the first time then you will need to +check that you have the required software packages, as described in the +*Prerequisites* section that follows. + +.. note:: + An online copy of the documentation is available at + https://www.trustedfirmware.org/docs/tf-a, if you want to view a rendered + copy without doing a local build. + +Prerequisites +------------- + +For building a local copy of the |TF-A| documentation you will need: + +- Python 3 (3.8 or later) +- PlantUML (1.2017.15 or later) +- `Poetry`_ (Python dependency manager) +- Optionally, the `Dia`_ application can be installed if you need to edit + existing ``.dia`` diagram files, or create new ones. + + +Below is an example set of instructions to get a working environment (tested on +Ubuntu): + +.. code:: shell + + sudo apt install python3 python3-pip plantuml [dia] + curl -sSL https://install.python-poetry.org | python3 - + +Building rendered documentation +------------------------------- + +To install Python dependencies using Poetry: + +.. code:: shell + + poetry install + +Poetry will create a new virtual environment and install all dependencies listed +in ``pyproject.toml``. You can get information about this environment, such as +its location and the Python version, with the command: + +.. code:: shell + + poetry env info + +If you have already sourced a virtual environment, Poetry will respect this and +install dependencies there. + +Once all dependencies are installed, the documentation can be compiled into +HTML-formatted pages from the project root directory by running: + +.. code:: shell + + poetry run make doc + +Output from the build process will be placed in: ``docs/build/html``. + +Other Output Formats +~~~~~~~~~~~~~~~~~~~~ + +We also support building documentation in other formats. From the ``docs`` +directory of the project, run the following command to see the supported +formats. + +.. code:: shell + + poetry run make -C docs help + +To build the documentation in PDF format, additionally ensure that the following +packages are installed: + +- FreeSerif font +- latexmk +- librsvg2-bin +- xelatex +- xindy + +Below is an example set of instructions to install the required packages +(tested on Ubuntu): + +.. code:: shell + + sudo apt install fonts-freefont-otf latexmk librsvg2-bin texlive-xetex xindy + +Once all the dependencies are installed, run the command ``poetry run make -C +docs latexpdf`` to build the documentation. Output from the build process +(``trustedfirmware-a.pdf``) can be found in ``docs/build/latex``. + +Building rendered documentation from Poetry's virtual environment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The command ``poetry run`` used in the steps above executes the input command +from inside the project's virtual environment. The easiest way to activate this +virtual environment is with the ``poetry shell`` command. + +Running ``poetry shell`` from the directory containing this project, activates +the same virtual environment. This creates a sub-shell through which you can +build the documentation directly with ``make``. + +.. code:: shell + + poetry shell + make doc + +Type ``exit`` to deactivate the virtual environment and exit this new shell. For +other use cases, please see the official `Poetry`_ documentation. + +Building rendered documentation from a container +------------------------------------------------ + +There may be cases where you can not either install or upgrade required +dependencies to generate the documents, so in this case, one way to +create the documentation is through a docker container. The first step is +to check if `docker`_ is installed in your host, otherwise check main docker +page for installation instructions. Once installed, run the following script +from project root directory + +.. code:: shell + + docker run --rm -v $PWD:/tf-a sphinxdoc/sphinx \ + bash -c 'cd /tf-a && + apt-get update && apt-get install -y curl plantuml && + curl -sSL https://install.python-poetry.org | python3 - && + ~/.local/bin/poetry install && ~/.local/bin/poetry run make doc' + +The above command fetches the ``sphinxdoc/sphinx`` container from `docker +hub`_, launches the container, installs documentation requirements and finally +creates the documentation. Once done, exit the container and output from the +build process will be placed in: ``docs/build/html``. + +-------------- + +*Copyright (c) 2019-2023, Arm Limited. All rights reserved.* + +.. _Sphinx: http://www.sphinx-doc.org/en/master/ +.. _Poetry: https://python-poetry.org/docs/ +.. _pip homepage: https://pip.pypa.io/en/stable/ +.. _Dia: https://wiki.gnome.org/Apps/Dia +.. _docker: https://www.docker.com/ +.. _docker hub: https://hub.docker.com/repository/docker/sphinxdoc/sphinx |