From 7be2b9838c3d0ff617eecb1c54749229ecd7ac2f Mon Sep 17 00:00:00 2001 From: Leonardo Sandoval Date: Wed, 10 Jun 2020 18:26:28 -0500 Subject: [PATCH] doc: use docker to build documentation docker (container) is another way to build the documentation and fortunately there is already a docker image (sphinxdoc/sphinx) with sphinx so we can use it to generate the documentation. Change-Id: I06b0621cd7509a8279655e828680b92241b9fde4 Signed-off-by: Leonardo Sandoval --- docs/getting_started/docs-build.rst | 29 ++++++++++++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/docs/getting_started/docs-build.rst b/docs/getting_started/docs-build.rst index 91b1b3a39..87c677fcd 100644 --- a/docs/getting_started/docs-build.rst +++ b/docs/getting_started/docs-build.rst @@ -67,7 +67,7 @@ Output from the build process will be placed in: :: - docs/build/html/ + docs/build/html We also support building documentation in other formats. From the ``docs`` directory of the project, run the following command to see the supported @@ -79,6 +79,31 @@ top-level Makefile for |TF-A| itself. make help +Building rendered documentation from a container +------------------------------------------------ + +There may be cases where you can not either install or upgrade required +dependencies to generate the documents, so in this case, one way to +create the documentation is through a docker container. The first step is +to check if `docker`_ is installed in your host, otherwise check main docker +page for installation instructions. Once installed, run the following script +from project root directory + +.. code:: shell + + docker run --rm -v $PWD:/TF sphinxdoc/sphinx \ + bash -c 'cd /TF && \ + pip3 install plantuml -r ./docs/requirements.txt && 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 + -------------- *Copyright (c) 2019, Arm Limited. All rights reserved.* @@ -86,3 +111,5 @@ top-level Makefile for |TF-A| itself. .. _Sphinx: http://www.sphinx-doc.org/en/master/ .. _pip homepage: https://pip.pypa.io/en/stable/ .. _Dia: https://wiki.gnome.org/Apps/Dia +.. _docker: https://www.docker.com/ +.. _docker hub: https://hub.docker.com/repository/docker/sphinxdoc/sphinx