docs: refactor build section
Under "Getting Started", created dedicated subsections for:
- Prerequisites
- Get Source
- Building
Signed-off-by: J-Alves <joao.alves@arm.com>
Change-Id: I46f7b924f812aea6f3bd3a9216fe2ccbec0287e8
diff --git a/docs/getting_started/building.rst b/docs/getting_started/building.rst
index cd8e2cf..bdd2873 100644
--- a/docs/getting_started/building.rst
+++ b/docs/getting_started/building.rst
@@ -1,87 +1,10 @@
-Building Hafnium
-================
-
-Prerequisites
--------------
-
-Build Host
-^^^^^^^^^^
-
-A relatively recent Linux distribution is recommended.
-CI runs are done using Ubuntu 22.04 LTS (64-bit).
-
-Toolchain
-^^^^^^^^^
-
-The following toolchain is recommended for building Hafnium and the test
-infrastructure:
-
-- For a x86_64 Ubuntu host,
-
-.. code:: shell
-
- https://github.com/llvm/llvm-project/releases/download/llvmorg-15.0.6/clang+llvm-15.0.6-x86_64-linux-gnu-ubuntu-18.04.tar.xz
-
-- For a AArch64 Ubuntu host,
-
-.. code:: shell
-
- https://github.com/llvm/llvm-project/releases/download/llvmorg-15.0.6/clang+llvm-15.0.6-aarch64-linux-gnu.tar.xz
-
-.. note::
-
- Use of a native toolchain installed on the host (e.g. /usr/bin/clang) is
- not supported.
-
-.. note::
-
- Using a toolchain version greater, or significantly lesser than the one
- specified is not guaranteed to work.
-
-.. _prerequisites_software_and_libraries:
-
-Dependencies
-^^^^^^^^^^^^
-
-If you are using the recommended Ubuntu distribution then you can install the
-required packages with the following command:
-
-.. code:: shell
-
- sudo apt install make libssl-dev flex bison python3 python3-serial
- python3-pip device-tree-compiler
-
- pip3 install fdt
-
-.. _prerequisites_get_source:
-
-Getting the sources
-^^^^^^^^^^^^^^^^^^^
-
-Hafnium source code is maintained in a Git repository hosted on
-trustedfirmware.org.
-To clone this repository from the server, run the following
-in your shell:
-
-.. code:: shell
-
- git clone --recurse-submodules https://git.trustedfirmware.org/hafnium/hafnium.git
-
-In order to import gerrit hooks useful to add a Change-Id footer in commit messages,
-it is recommended to use:
-
-.. code:: shell
-
- git clone --recurse-submodules https://git.trustedfirmware.org/hafnium/hafnium.git && { cd hafnium && f="$(git rev-parse --git-dir)"; curl -Lo "$f/hooks/commit-msg" https://review.trustedfirmware.org/tools/hooks/commit-msg && { chmod +x "$f/hooks/commit-msg"; git submodule --quiet foreach "cp \"\$toplevel/$f/hooks/commit-msg\" \"\$toplevel/$f/modules/\$path/hooks/commit-msg\""; }; }
-
Building
---------
+========
-The PATH environment variable shall be adjusted to the LLVM/clang directory, prior to building e.g.:
+This page assumes the :ref:`Prerequisites` have been followed to install all project dependencies.
-.. code:: shell
-
- PATH=<toolchain_dir>/clang+llvm-15.0.6-x86_64-linux-gnu-ubuntu-18.04/bin:$PATH
+Hafnium
+^^^^^^^
By default, the Hafnium SPMC is built with clang for a few target platforms along
with tests. From Hafnium top level directory, simply type:
@@ -117,6 +40,16 @@
So the `args.gn` file will be regenerated with the new values.
+Hafnium Documentation
+^^^^^^^^^^^^^^^^^^^^^
+
+If you have already sourced a virtual environment, Poetry will respect this and
+install dependencies there.
+
+.. code:: shell
+
+ poetry run make doc
+
--------------
*Copyright (c) 2023, Arm Limited. All rights reserved.*
diff --git a/docs/getting_started/docs-build.rst b/docs/getting_started/docs-build.rst
deleted file mode 100644
index 618aab0..0000000
--- a/docs/getting_started/docs-build.rst
+++ /dev/null
@@ -1,80 +0,0 @@
-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/get-source.rst b/docs/getting_started/get-source.rst
new file mode 100644
index 0000000..a71a670
--- /dev/null
+++ b/docs/getting_started/get-source.rst
@@ -0,0 +1,20 @@
+Getting the source code
+=======================
+
+Hafnium source code is maintained in a Git repository hosted on trustedfirmware.org.
+To clone this repository from the server, run the following in your shell:
+
+.. code:: shell
+
+ git clone --recurse-submodules https://git.trustedfirmware.org/hafnium/hafnium.git
+
+In order to import gerrit hooks useful to add a Change-Id footer in commit messages,
+it is recommended to use:
+
+.. code:: shell
+
+ git clone --recurse-submodules https://git.trustedfirmware.org/hafnium/hafnium.git && { cd hafnium && f="$(git rev-parse --git-dir)"; curl -Lo "$f/hooks/commit-msg" https://review.trustedfirmware.org/tools/hooks/commit-msg && { chmod +x "$f/hooks/commit-msg"; git submodule --quiet foreach "cp \"\$toplevel/$f/hooks/commit-msg\" \"\$toplevel/$f/modules/\$path/hooks/commit-msg\""; }; }
+
+--------------
+
+*Copyright (c) 2023, Arm Limited. All rights reserved.*
diff --git a/docs/getting_started/index.rst b/docs/getting_started/index.rst
index c7ca45e..dc780a2 100644
--- a/docs/getting_started/index.rst
+++ b/docs/getting_started/index.rst
@@ -5,8 +5,9 @@
:maxdepth: 1
:caption: Contents
+ prerequisites
+ get-source
building
- docs-build
coding-style
commit-style
diff --git a/docs/getting_started/prerequisites.rst b/docs/getting_started/prerequisites.rst
new file mode 100644
index 0000000..5fd04ac
--- /dev/null
+++ b/docs/getting_started/prerequisites.rst
@@ -0,0 +1,104 @@
+Prerequisites
+=============
+
+Build Host
+----------
+
+A relatively recent Linux distribution is recommended.
+CI runs are done using Ubuntu 22.04 LTS (64-bit).
+
+Toolchain
+---------
+
+The following toolchain is recommended for building Hafnium and the test
+infrastructure:
+
+- For a x86_64 Ubuntu host,
+
+.. code:: shell
+
+ https://github.com/llvm/llvm-project/releases/download/llvmorg-15.0.6/clang+llvm-15.0.6-x86_64-linux-gnu-ubuntu-18.04.tar.xz
+
+- For a AArch64 Ubuntu host,
+
+.. code:: shell
+
+ https://github.com/llvm/llvm-project/releases/download/llvmorg-15.0.6/clang+llvm-15.0.6-aarch64-linux-gnu.tar.xz
+
+.. note::
+
+ Use of a native toolchain installed on the host (e.g. /usr/bin/clang) is
+ not supported.
+
+.. note::
+
+ Using a toolchain version greater, or significantly lesser than the one
+ specified is not guaranteed to work.
+
+The PATH environment variable shall be adjusted to contain the LLVM/clang directory, e.g.:
+
+.. code:: shell
+
+ PATH=<toolchain_dir>/clang+llvm-15.0.6-x86_64-linux-gnu-ubuntu-18.04/bin:$PATH
+
+Dependencies
+------------
+
+Build
+^^^^^
+
+The following command install the dependencies for the Hafnium build:
+
+.. code:: shell
+
+ sudo apt install make libssl-dev flex bison python3 python3-serial python3-pip device-tree-compiler
+
+In addion, install the following python lib using `pip`_:
+
+.. code:: shell
+
+ pip3 install fdt
+
+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.
+
+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 -
+
+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
+
+--------------
+
+*Copyright (c) 2023, Arm Limited. All rights reserved.*
+
+.. _Sphinx: http://www.sphinx-doc.org/en/master/
+.. _Poetry: https://python-poetry.org/docs/
+.. _pip: https://pip.pypa.io/en/stable/
+