build(poetry): wrap docs build in poetry
Simplify building documentation by wrapping the Sphinx command inside
a Poetry environment. Previously, the developer had to manually
activate Poetry and install the docs group. This change makes the
process consistent with other build targets and reduces user error.
Falls back gracefully if Poetry is not installed.
Change-Id: I1dfea58314253773bec5e2c70d27e2216e3143d9
Signed-off-by: Harrison Mutai <harrison.mutai@arm.com>
diff --git a/docs/getting_started/docs-build.rst b/docs/getting_started/docs-build.rst
index 54e29dd..e11da77 100644
--- a/docs/getting_started/docs-build.rst
+++ b/docs/getting_started/docs-build.rst
@@ -42,7 +42,7 @@
.. code:: shell
- poetry run make doc
+ make doc
Output from the build process will be placed in: ``docs/build/html``.
@@ -55,7 +55,7 @@
.. code:: shell
- poetry run make -C docs help
+ make -C docs help
To build the documentation in PDF format, additionally ensure that the following
packages are installed:
@@ -80,9 +80,10 @@
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.
+If Poetry is installed, the ``doc`` target wraps its build steps with ``poetry
+run``, which runs the specified command within the project's virtual
+environment. The easiest way to activate this environment manually is by using
+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
@@ -91,7 +92,7 @@
.. code:: shell
poetry shell
- make doc
+ make -C docs html
Type ``exit`` to deactivate the virtual environment and exit this new shell. For
other use cases, please see the official `Poetry`_ documentation.
@@ -121,7 +122,7 @@
--------------
-*Copyright (c) 2019-2024, Arm Limited. All rights reserved.*
+*Copyright (c) 2019-2025, Arm Limited. All rights reserved.*
.. _Sphinx: http://www.sphinx-doc.org/en/master/
.. _Poetry: https://python-poetry.org/docs/