Merge "docs: patch Poetry build instructions" into integration

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 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:
+Output from the build process will be placed in: ``docs/build/html``.
 
-::
-
-   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 ``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.
+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``.
+
+.. 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/

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)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^