Merge "docs: patch Poetry build instructions" into integration
diff --git a/docs/getting_started/docs-build.rst b/docs/getting_started/docs-build.rst
index 99cba1e..aa8c2bb 100644
--- a/docs/getting_started/docs-build.rst
+++ b/docs/getting_started/docs-build.rst
@@ -21,57 +21,77 @@
- 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 @@
.. 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 f30216a..bf10ecf 100644
--- a/docs/getting_started/prerequisites.rst
+++ b/docs/getting_started/prerequisites.rst
@@ -100,10 +100,10 @@
- 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)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^