diff options
author | Minos Galanakis <minos.galanakis@arm.com> | 2020-06-03 15:38:03 +0100 |
---|---|---|
committer | Tamas Ban <tamas.ban@arm.com> | 2020-09-24 12:49:54 +0000 |
commit | d19a19f161148b97f3ec8ccec7baebd79599f8c4 (patch) | |
tree | b7d1f354d0a33d533b74f7bcdc3b9865b360504e /docs | |
parent | 7b95029a5864ce834e9535ce96da92be3f418a54 (diff) | |
download | trusted-firmware-m-d19a19f161148b97f3ec8ccec7baebd79599f8c4.tar.gz |
Docs: Decouple from CMAKE and enable sphynx-build.
This patch is reducing the dependency of the documentation to
the TrustedFirmware-M build environment. Currently CMake will
copy over files from platforms, render the configuration files,
sort design documents and invoke the corresponding tools to
build the documentation.
This patch introduces an environment communicating interface file,
which CMAKE will need to populate, before calling the build command.
The file copy operation has been moved over to the sphynx-build logic,
and the design document’s classification is no longer required by the
new user interface.
The new implemenatation allows:
* Documentation can be built in an identical way through the build system,
retaining compatibility with existing tools, such as the CI.
* It is now possible to build documentation, by just invoking sphynx-build
from the build-docs directory.
* Third party tools/services like readthedocs.org can now render
the TF-M documentation.
* Reduced CMake code size.
* Documentation generating logic invokes ‘git describe’ in order to determine
a version. The order of precedence is set as:
Git Describe Version-> CMake hardcoded version -> Template version.
* CMake logic can still toggle parts of the new logic on and off if required.
* The full set of TF-M build dependencies are not longer required in order
to build documentation. Just the documentation dependencies would suffice.
Change-Id: I12e7bbffe9d1adb756329c46da13905e95096381
Signed-off-by: Minos Galanakis <minos.galanakis@arm.com>
Diffstat (limited to 'docs')
-rw-r--r-- | docs/getting_started/tfm_build_instruction.rst | 41 | ||||
-rw-r--r-- | docs/tfm_env.py.in | 28 |
2 files changed, 64 insertions, 5 deletions
diff --git a/docs/getting_started/tfm_build_instruction.rst b/docs/getting_started/tfm_build_instruction.rst index 29982c0d68..a8e890b63c 100644 --- a/docs/getting_started/tfm_build_instruction.rst +++ b/docs/getting_started/tfm_build_instruction.rst @@ -176,9 +176,17 @@ Further details on how to integrate a new NS app with TF-M are available in the Building the documentation ========================== -Please ensure the dependencies for building the firmware and the -documentation are installed as explained in the -:doc:`software requirements <tfm_sw_requirement>`. +Please ensure the dependencies for building the documentation are installed +as explained in the :doc:`software requirements <tfm_sw_requirement>`. The +requirements to build the firmware, are only required when using the CMAKE +method + +There are currently two ways of building the documentation: +- Using the CMake build system as custom targets +- Manually using the appropriate tools (`sphinx-build`_/ `Doxygen`_) + +Using the CMake build-system +---------------------------- Building PDF output is optional and can be disabled by removing LaTex from the PATH. @@ -188,7 +196,7 @@ PATH. be available. Building the Reference Manual ------------------------------ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: bash cd <TF-M base folder> @@ -202,7 +210,7 @@ The documentation files will be available under the directory:: cmake_doc/install/doc/reference_manual Building the User Guide ------------------------ +^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: bash cd <TF-M base folder> @@ -215,6 +223,26 @@ The documentation files will be available under the directory:: cmake_doc/install/doc/user_guide +Manually using documentation generation tools +--------------------------------------------- + +Invoking Sphinx-build will build both user_guide and reference_manual +targets. + +.. code-block:: bash + + # Build the documentation from build_docs directory + cd <TF-M base folder>/ build_docs/ + sphinx-build ./ user_guide + + # Build the documentation from a custom location + # setting the build_docs as input + + # Note that using this method will still generate the reference manual + # to the <TF-M base folder>/build_docs/reference_manual + cd <TF-M base folder>/OTHER_DIR/OTHER_DIR2 + sphinx-build <TF-M base folder>/build_docs/ DESIRED_OUTPUT_DIR + ********************* Configuring the build ********************* @@ -344,6 +372,9 @@ The following table describes the differences between the configurations: .. [7] Profile Small config doesn't cover all the platforms. Please check Profile Small config files to find out the supported platforms. +.. _sphinx-build: https://www.sphinx-doc.org/en/master/man/sphinx-build.html +.. _Doxygen: https://www.doxygen.nl + -------------- *Copyright (c) 2017-2020, Arm Limited. All rights reserved.* diff --git a/docs/tfm_env.py.in b/docs/tfm_env.py.in new file mode 100644 index 0000000000..b96be484d6 --- /dev/null +++ b/docs/tfm_env.py.in @@ -0,0 +1,28 @@ +# ----------------------------------------------------------------------------- +# Copyright (c) 2020, Arm Limited. All rights reserved. +# +# SPDX-License-Identifier: BSD-3-Clause +# +# ----------------------------------------------------------------------------- + +# Interface file between cmake and sphynx-build. Variables will be populated +# by cmake and evaluated by the Python builder + +cmake_env = { "SPHINX_TMP_DOC_DIR": "@SPHINX_TMP_DOC_DIR@", + "TFM_ROOT_DIR" : "@TFM_ROOT_DIR@", + "PLANTUML_JAR_PATH" : "@PLANTUML_JAR_PATH@", + "Java_JAVA_EXECUTABLE" : "@Java_JAVA_EXECUTABLE@", + "SPHINX_TMP_DOC_DIR" : "@SPHINX_TMP_DOC_DIR@", + "DOXYGEN_EXECUTABLE" : "@DOXYGEN_EXECUTABLE@", + "DOXYGEN_DOT_EXECUTABLE" : "@DOXYGEN_DOT_EXECUTABLE@", + "DOXYCFG_DOXYGEN_CFG_DIR": "@DOXYCFG_DOXYGEN_CFG_DIR@", + "DOXYCFG_OUTPUT_PATH": "@DOXYCFG_OUTPUT_PATH@", + "DOXYCFG_DOXYGEN_BUILD": "@DOXYCFG_DOXYGEN_BUILD@", + "DOXYCFG_ECLIPSE_DOCID": "@DOXYCFG_ECLIPSE_DOCID@", + "SPHINXCFG_TEMPLATE_FILE": "@SPHINXCFG_TEMPLATE_FILE@", + "PDF_OUTPUT_FILE": "@_PDF_FILE@", + "SPHINXCFG_COPY_FILES": "@SPHINXCFG_COPY_FILES@", + "SPHINXCFG_RENDER_CONF": "@SPHINXCFG_RENDER_CONF@", + "SPHINXCFG_TFM_VERSION" : "@SPHINXCFG_TFM_VERSION@", + "SPHINXCFG_TFM_VERSION_FULL" : "@SPHINXCFG_TFM_VERSION_FULL@" + } |