docs: patch Poetry build instructions

Some parts of the documentation referring to Poetry provides incorrect
build instructions and has some minor formatting errors. Reformat the
bits that require formatting, and fix the build instructions. These
were originally part of the patch stack that added Poetry support but
were accidentally reverted prior to merge.

Signed-off-by: Harrison Mutai <harrison.mutai@arm.com>
Change-Id: I336d3a7bbe99f75262430ae436f8ebc2cb050d2c

diff --git a/docs/getting_started/docs-build.rst b/docs/getting_started/docs-build.rst
index 99cba1ec0a62892a5e223aaa88334a22de48c86f..aa8c2bbf67124304ef9453f5e24e0106297d71dd 100644 (file)
--- a/docs/getting_started/docs-build.rst
+++ b/docs/getting_started/docs-build.rst
@@ -21,57 +21,77 @@ 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 and package manager
-- Python modules specified in ``pyproject.toml``
+- `Poetry`_ (Python dependency manager)
 - Optionally, the `Dia`_ application can be installed if you need to edit
   existing ``.dia`` diagram files, or create new ones.
 
 
-Poetry will handle the creation of a virtual build environment, either creating
-a new environment or re-using one created by the user, and installing all
-dependencies herein. This ensures that the Python environment is isolated from
-your system environment.
-
-An example set of installation commands for Ubuntu follows:
+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 -
-    poetry install
 
 Building rendered documentation
 -------------------------------
 
-Documents can be built into HTML-formatted pages from project root directory by
-running the following command.
+To install Python dependencies using Poetry:
 
 .. code:: shell
 
-   poetry run make doc
+    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:
 
-Output from the build process will be placed in:
+.. code:: shell
 
-::
+    poetry env info
 
-   docs/build/html
+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. It is important to note that you will not get the correct result if
-the command is run from the project root directory, as that would invoke the
-top-level Makefile for |TF-A| itself.
+formats.
 
 .. code:: shell
 
-   poetry run make help
+   poetry run make -C docs help
 
-.. note::
+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``.
 
-   The ``run`` command used above executes ``make`` in the projects virtual
-   environment. To spawn a shell in this environment, use ``poetry
-   shell``. For other use cases, please see the official `Poetry`_
-   documentation.
+.. 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
 ------------------------------------------------
@@ -85,25 +105,23 @@ from project root directory
 
 .. code:: shell
 
-   docker run --rm -v $PWD:/TF sphinxdoc/sphinx \
-          bash -c 'cd /TF && \
-          poetry install && poetry run make doc'
+   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 install && ~/.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
+build process will be placed in: ``docs/build/html``.
 
 --------------
 
 *Copyright (c) 2019-2023, Arm Limited. All rights reserved.*
 
 .. _Sphinx: http://www.sphinx-doc.org/en/master/
-.. _Poetry: https://python-poetry.org/docs/cli/
+.. _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/

diff --git a/docs/getting_started/prerequisites.rst b/docs/getting_started/prerequisites.rst
index f30216a24c4bf5bd503794a86a370adfce0d14f3..bf10ecffb4ced32d3a4ca31bff0db5e4b5ebee37 100644 (file)
--- a/docs/getting_started/prerequisites.rst
+++ b/docs/getting_started/prerequisites.rst
@@ -100,10 +100,10 @@ These tools are optional:
 
 - Poetry >= 1.3.2
 
-  Required for managing Python dependencies, this will allow you to reliably
-  reproduce a Python environment to build documentation and run analysis tools.
-  Most importantly, it ensures your system environment will not be affected by
-  dependencies in the Python scripts.
+   Required for managing Python dependencies, this will allow you to reliably
+   reproduce a Python environment to build documentation and run analysis tools.
+   Most importantly, it ensures your system environment will not be affected by
+   dependencies in the Python scripts.
 
 Package Installation (Linux)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^