diff --git a/docs/getting_started/docs-build.rst b/docs/getting_started/docs-build.rst index 99cba1ec0..aa8c2bbf6 100644 --- 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 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/ diff --git a/docs/getting_started/prerequisites.rst b/docs/getting_started/prerequisites.rst index f30216a24..bf10ecffb 100644 --- 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) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^