docs: add getting started section and docs build
Signed-off-by: Olivier Deprez <olivier.deprez@arm.com>
Change-Id: I45e961f52b7af57fe6599bde623fb75093c7cad9
diff --git a/docs/getting_started/docs-build.rst b/docs/getting_started/docs-build.rst
new file mode 100644
index 0000000..618aab0
--- /dev/null
+++ b/docs/getting_started/docs-build.rst
@@ -0,0 +1,80 @@
+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://hafnium.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:
+
+- Python 3 (3.8 or later)
+- PlantUML (1.2017.15 or later)
+- `Poetry`_ (Python dependency manager)
+
+Below is an example set of instructions to get a working environment (tested on
+Ubuntu):
+
+.. code:: shell
+
+ sudo apt install python3 python3-pip plantuml
+ 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
+
+--------------
+
+*Copyright (c) 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/
diff --git a/docs/getting_started/index.rst b/docs/getting_started/index.rst
new file mode 100644
index 0000000..1b18f68
--- /dev/null
+++ b/docs/getting_started/index.rst
@@ -0,0 +1,12 @@
+Getting Started
+===============
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Contents
+
+ docs-build
+
+--------------
+
+*Copyright (c) 2023, Arm Limited. All rights reserved.*
diff --git a/docs/index.rst b/docs/index.rst
index 1971007..11d8cf2 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -6,6 +6,7 @@
:numbered:
about/index
+ getting_started/index
design/index
threat_model_spm
change-log