docs: add instructions for building the docs
Although building these docs is mostly done through the standard
sphinx-build command, some additional dependencies and environment
variables are required for PlantUML and Graphviz generation to work
properly.
The first section is adapted from the main TF-M documentation.
Change-Id: I670b6361e9904166a3babccbabeac655f247699a
Signed-off-by: Nik Dewally <Nik.Dewally@arm.com>
diff --git a/.gitignore b/.gitignore
index f9ffdce..504a3b6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -17,3 +17,7 @@
# Visual Studio Code
.vscode/
+
+# build files
+build*/
+
diff --git a/docs/doc_build.rst b/docs/doc_build.rst
new file mode 100644
index 0000000..c4405d5
--- /dev/null
+++ b/docs/doc_build.rst
@@ -0,0 +1,80 @@
+##########################
+Building the documentation
+##########################
+
+******************************
+Tools and building environment
+******************************
+
+These tools are used to generate TF-M Tools documentation:
+
+ - Graphviz dot v2.38.0 or later
+ - PlantUML v1.2018.11 or later
+ - Java runtime environment v1.8 or later (for running PlantUML)
+ - Sphinx and other python modules, listed in ``docs/requirements.txt``
+
+
+To prepare your building environment execute the following steps:
+
+.. tabs::
+
+ .. group-tab:: Linux
+
+ Install the required tools:
+
+ .. code-block:: bash
+
+ sudo apt-get install -y graphviz default-jre
+ mkdir ~/plantuml
+ curl -L http://sourceforge.net/projects/plantuml/files/plantuml.jar/download --output ~/plantuml/plantuml.jar
+
+ # Install the required Python modules
+ pip3 install --upgrade pip
+ cd <tf-m-tools base folder>
+ pip3 install -r docs/requirements.txt
+
+ Set the environment variables:
+
+ .. code-block:: bash
+
+ export PLANTUML_JAR_PATH=~/plantuml/plantuml.jar
+
+ .. group-tab:: Windows
+
+ Download and install the following tools:
+
+ - `Graphviz 2.38 <https://graphviz.gitlab.io/_pages/Download/windows/graphviz-2.38.msi>`__
+ - The Java runtime is part of the Arm DS installation or can be downloaded from `here <https://www.java.com/en/download/>`__
+ - `PlantUML <http://sourceforge.net/projects/plantuml/files/plantuml.jar/download>`__
+
+ Set the environment variables, assuming that:
+
+ - dot binaries are available on the PATH.
+ - Java JVM is used from Arm DS installation.
+
+ .. code-block:: bash
+
+ set PLANTUML_JAR_PATH=<plantuml_Path>\plantuml.jar
+ set PATH=$PATH;<ARM_DS_PATH>\sw\java\bin
+
+ # Install the required Python modules
+ pip3 install --upgrade pip
+ cd <tf-m-tools base folder>
+ pip3 install -r docs\requirements.txt
+
+
+*********************
+Build TF-M Tools Docs
+*********************
+
+From the root directory of this repository, run:
+
+.. code-block:: bash
+
+ sphinx-build -M html docs build_docs
+
+The generated HTML documentation can be found in `build_docs/html`.
+
+
+*Copyright (c) 2024, Arm Limited. All rights reserved.*
+
diff --git a/docs/index.rst b/docs/index.rst
index dea768a..6c94274 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,6 +1,6 @@
-################################
+########################
Trusted Firmware-M Tools
-################################
+########################
.. toctree::
:caption: Overview
@@ -19,6 +19,12 @@
TF-M Manual Build <tf-m-manual-build>
.. toctree::
+ :caption: Development
+ :titlesonly:
+
+ Building the Documentation <doc_build>
+
+.. toctree::
:caption: Links
:maxdepth: 1
:hidden:
@@ -29,4 +35,4 @@
--------------
-*Copyright (c) 2017-2023, Arm Limited. All rights reserved.*
+*Copyright (c) 2017-2024, Arm Limited. All rights reserved.*