doc: Explain how to locally build the documentation
Add a document that provides instructions on how to build a rendered
version of the documentation using the Sphinx tool.
Change-Id: I57159ec867a3ba7e003e7c7cd6ac53fb190356f2
Signed-off-by: Sandrine Bailleux <sandrine.bailleux@arm.com>
diff --git a/docs/getting_started/docs-build.rst b/docs/getting_started/docs-build.rst
new file mode 100644
index 0000000..6a6992b
--- /dev/null
+++ b/docs/getting_started/docs-build.rst
@@ -0,0 +1,84 @@
+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://trustedfirmware-a-tests.readthedocs.io, if you want to view a
+ rendered copy without doing a local build.
+
+Prerequisites
+-------------
+
+For building a local copy of the documentation you will need, at minimum:
+
+- Python 3 (3.5 or later)
+- PlantUML (1.2017.15 or later)
+
+You must also install the Python modules that are specified in the
+``requirements.txt`` file in the root of the ``docs`` directory. These modules
+can be installed using ``pip3`` (the Python Package Installer). Passing this
+requirements file as an argument to ``pip3`` automatically installs the specific
+module versions required by TF-A Tests.
+
+An example set of installation commands for Ubuntu 18.04 LTS follows, assuming
+that the working directory is ``docs``:
+
+.. code:: shell
+
+ sudo apt install python3 python3-pip plantuml
+ pip3 install [--user] -r requirements.txt
+
+.. note::
+ Several other modules will be installed as dependencies. Please review
+ the list to ensure that there will be no conflicts with other modules already
+ installed in your environment.
+
+Passing the optional ``--user`` argument to ``pip3`` will install the Python
+packages only for the current user. Omitting this argument will attempt to
+install the packages globally and this will likely require the command to be run
+as root or using ``sudo``.
+
+.. note::
+ More advanced usage instructions for *pip* are beyond the scope of this
+ document but you can refer to the `pip homepage`_ for detailed guides.
+
+Building rendered documentation
+-------------------------------
+
+The documentation can be built into HTML-formatted pages from the project's root
+directory by running the following command.
+
+.. code:: shell
+
+ make doc
+
+Output from the build process will be placed in:
+
+::
+
+ docs/build/html/
+
+We also support building documentation in other formats. From the ``docs``
+directory of the project, run the following command to see the supported
+formats. It is important to note that you will not get the correct result if the
+command is run from the project's root directory, as that would invoke the
+top-level Makefile for TF-A Tests themselves.
+
+.. code:: shell
+
+ make help
+
+--------------
+
+*Copyright (c) 2020, Arm Limited. All rights reserved.*
+
+.. _Sphinx: http://www.sphinx-doc.org/en/master/
+.. _pip homepage: https://pip.pypa.io/en/stable/
diff --git a/docs/getting_started/index.rst b/docs/getting_started/index.rst
index a956efb..42a0b5b 100644
--- a/docs/getting_started/index.rst
+++ b/docs/getting_started/index.rst
@@ -5,6 +5,7 @@
:maxdepth: 1
requirements
+ docs-build
obtain
build
build-options
@@ -16,6 +17,6 @@
--------------
-*Copyright (c) 2019, Arm Limited. All rights reserved.*
+*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
.. _Trusted Firmware-A (TF-A): https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git