mirror of
https://github.com/ARM-software/arm-trusted-firmware.git
synced 2025-04-08 05:43:53 +00:00
9db2b059eb
Signed-off-by: Tamas Ban <tamas.ban@arm.com> Change-Id: I8ee666ee4cd135d09380ce31751ddba9962ff831
131 lines
4.3 KiB
ReStructuredText
131 lines
4.3 KiB
ReStructuredText
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
|
|
-------------------------------
|
|
|
|
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 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-2024, 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
|