docs: Decouple documentation build from the main
- Documentation is a standalone CMake project in /docs
- Exclude TFM_VERSION to a dedicated version.cmake file
- Move /doxygen into /docs folder
- Adjust documentation for building documentation :)
- Suppress warnings of PythonModules mismatch in docs build
Signed-off-by: Anton Komlev <anton.komlev@arm.com>
Change-Id: I726dc17d9aa547b8faaf35564e21f25aa9c207a9
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 2a75bfd..b46706d 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -7,7 +7,7 @@
cmake_minimum_required(VERSION 3.15)
-set(TFM_VERSION 1.4.0)
+include(version.cmake)
############################ CONFIGURATION #####################################
@@ -93,7 +93,6 @@
add_subdirectory(lib/ext)
add_subdirectory(lib/fih)
add_subdirectory(tools)
-add_subdirectory(docs)
if(NS)
# Set to ${TFM_TEST_REPO_PATH}/app by default
add_subdirectory(${TFM_APP_PATH} ${CMAKE_CURRENT_BINARY_DIR}/app)
diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
index 78b7570..f1a2b2d 100644
--- a/docs/CMakeLists.txt
+++ b/docs/CMakeLists.txt
@@ -9,8 +9,13 @@
add_custom_target(docs)
+list(APPEND CMAKE_MODULE_PATH ${CMAKE_SOURCE_DIR}/../cmake)
+
find_package(Python3)
find_package(Sphinx)
+
+# suppress warnings on mismatched names in PythonModules
+set(FPHSA_NAME_MISMATCHED True)
find_package(PythonModules COMPONENTS m2r sphinx-rtd-theme sphinxcontrib.plantuml)
find_package(PlantUML)
find_package(Doxygen 1.8.0)
@@ -18,6 +23,10 @@
################################## ENV #########################################
+include(../version.cmake)
+
+project("Trusted Firmware M. Documentation" VERSION ${TFM_VERSION} LANGUAGES)
+
set(SPHINXCFG_OUTPUT_PATH ${CMAKE_CURRENT_BINARY_DIR}/user_guide)
set(SPHINX_TMP_DOC_DIR ${CMAKE_CURRENT_BINARY_DIR}/temp)
set(SPHINXCFG_TEMPLATE_FILE "${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in")
@@ -36,8 +45,8 @@
)
add_custom_command(OUTPUT ${SPHINX_TMP_DOC_DIR}/conf.py
COMMAND ${CMAKE_COMMAND} -E make_directory ${SPHINX_TMP_DOC_DIR}
- COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_SOURCE_DIR}/docs/conf.py ${SPHINX_TMP_DOC_DIR}/conf.py
- MAIN_DEPENDENCY ${CMAKE_SOURCE_DIR}/docs/conf.py
+ COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_SOURCE_DIR}/conf.py ${SPHINX_TMP_DOC_DIR}/conf.py
+ MAIN_DEPENDENCY ${CMAKE_SOURCE_DIR}/conf.py
BYPRODUCTS ${SPHINX_TMP_DOC_DIR}
)
@@ -54,7 +63,7 @@
DEPENDS tfm_docs_sphinx_cfg
DEPENDS ${SPHINXCFG_DOC_FILES}
)
- add_custom_target(tfm_docs_userguide_html
+ add_custom_target(tfm_docs_userguide_html ALL
DEPENDS "${SPHINXCFG_OUTPUT_PATH}/html/index.html"
DEPENDS "${SPHINXCFG_OUTPUT_PATH}/html/"
)
@@ -96,7 +105,7 @@
WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
DEPENDS ${DOXYCFG_DOC_FILES}
)
- add_custom_target(tfm_docs_refman_html
+ add_custom_target(tfm_docs_refman_html ALL
WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
DEPENDS ${DOXYCFG_OUTPUT_PATH}/html
)
diff --git a/doxygen/Doxyfile.in b/docs/doxygen/Doxyfile.in
similarity index 99%
rename from doxygen/Doxyfile.in
rename to docs/doxygen/Doxyfile.in
index 60b1ea4..4bf2738 100644
--- a/doxygen/Doxyfile.in
+++ b/docs/doxygen/Doxyfile.in
@@ -58,7 +58,7 @@
# pixels and the maximum width should not exceed 200 pixels. Doxygen will copy
# the logo to the output directory.
-PROJECT_LOGO = @CMAKE_SOURCE_DIR@/doxygen/TrustedFirmware-Logo_icon.png
+PROJECT_LOGO = doxygen/TrustedFirmware-Logo_icon.png
# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path
# into which the generated documentation will be written. If a relative path is
@@ -169,7 +169,7 @@
# will be relative from the directory where doxygen is started.
# This tag requires that the tag FULL_PATH_NAMES is set to YES.
-STRIP_FROM_PATH = "@CMAKE_SOURCE_DIR@"
+STRIP_FROM_PATH = ".."
# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the
# path mentioned in the documentation of a class, which tells the reader which
@@ -178,7 +178,7 @@
# specify the list of include paths that are normally passed to the compiler
# using the -I flag.
-STRIP_FROM_INC_PATH = "@CMAKE_SOURCE_DIR@"
+STRIP_FROM_INC_PATH = ".."
# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but
# less readable) file names. This can be useful is your file systems doesn't
@@ -797,10 +797,10 @@
# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
# Note: If this tag is empty the current directory is searched.
-INPUT = "@CMAKE_SOURCE_DIR@/doxygen" \
- "@CMAKE_SOURCE_DIR@/interface" \
- "@CMAKE_SOURCE_DIR@/secure_fw" \
- "@CMAKE_SOURCE_DIR@/test"
+INPUT = "doxygen" \
+ "../interface" \
+ "../secure_fw" \
+ "../test"
# This tag can be used to specify the character encoding of the source files
diff --git a/doxygen/TrustedFirmware-Logo_icon.png b/docs/doxygen/TrustedFirmware-Logo_icon.png
similarity index 100%
rename from doxygen/TrustedFirmware-Logo_icon.png
rename to docs/doxygen/TrustedFirmware-Logo_icon.png
Binary files differ
diff --git a/doxygen/mainpage.dox b/docs/doxygen/mainpage.dox
similarity index 100%
rename from doxygen/mainpage.dox
rename to docs/doxygen/mainpage.dox
diff --git a/docs/technical_references/instructions/documentation_generation.rst b/docs/technical_references/instructions/documentation_generation.rst
index e6b4fc5..72e7e55 100644
--- a/docs/technical_references/instructions/documentation_generation.rst
+++ b/docs/technical_references/instructions/documentation_generation.rst
@@ -7,10 +7,8 @@
- Reference Manual. Doxygen based.
- User Guide. Sphinx based.
-Both documents can be generated in HTML and PDF format.
-
-Support for document generation in the build environment is not mandatory.
-Missing document generation tools will not block building the TF-M firmware.
+Both documents can be generated in HTML and PDF format and independently from
+building the project binary artifacts.
***************************
Build TF-M Reference Manual
@@ -48,8 +46,8 @@
.. code-block:: bash
cd <TF-M base folder>
- cmake -S . -B cmake_doc -DTFM_PLATFORM=arm/mps2/an521
- cmake --build cmake_doc -- tfm_docs_refman_html tfm_docs_refman_pdf
+ cmake -S docs -B build_docs
+ cmake --build build_docs -- tfm_docs_refman_html tfm_docs_refman_pdf
The documentation files will be available under the directory ``cmake_doc/docs/reference_manual``.
@@ -104,10 +102,10 @@
.. code-block:: bash
cd <TF-M base folder>
- cmake -S . -B cmake_doc -DTFM_PLATFORM=arm/mps2/an521
- cmake --build cmake_doc -- tfm_docs_refman_html tfm_docs_refman_pdf
+ cmake -S docs -B build_docs -G"Unix Makefiles"
+ cmake --build build_docs -- tfm_docs_refman_html tfm_docs_refman_pdf
- The documentation files will be available under the directory ``cmake_doc\docs\reference_manual``.
+ The documentation files will be available under the directory ``build_docs\docs\reference_manual``.
*********************
Build TF-M User Guide
@@ -154,10 +152,10 @@
.. code-block:: bash
cd <TF-M base folder>
- cmake -S . -B cmake_doc -DTFM_PLATFORM=arm/mps2/an521
- cmake --build cmake_doc -- tfm_docs_userguide_html tfm_docs_userguide_pdf
+ cmake -S docs -B build_docs
+ cmake --build build_docs -- tfm_docs_userguide_html tfm_docs_userguide_pdf
- The documentation files will be available under the directory ``cmake_doc/docs/user_guide``.
+ The documentation files will be available under the directory ``build_docs/docs/user_guide``.
- Manually using the appropriate tools (`sphinx-build`_/ `Doxygen`_)
@@ -222,10 +220,10 @@
.. code-block:: bash
cd <TF-M base folder>
- cmake -S . -B cmake_doc -DTFM_PLATFORM=arm/mps2/an521
- cmake --build cmake_doc -- tfm_docs_userguide_html tfm_docs_userguide_pdf
+ cmake -S docs -B build_docs -G"Unix Makefiles"
+ cmake --build build_docs -- tfm_docs_userguide_html tfm_docs_userguide_pdf
- The documentation files will be available under the directory ``cmake_doc\docs\user_guide``.
+ The documentation files will be available under the directory ``build_docs\docs\user_guide``.
.. _sphinx-build: https://www.sphinx-doc.org/en/master/man/sphinx-build.html
.. _Doxygen: https://www.doxygen.nl
diff --git a/docs/tfm_env.py.in b/docs/tfm_env.py.in
index cc2f8bf..16292d2 100644
--- a/docs/tfm_env.py.in
+++ b/docs/tfm_env.py.in
@@ -9,7 +9,7 @@
# by cmake and evaluated by the Python builder
cmake_env = { "SPHINX_TMP_DOC_DIR" : "@SPHINX_TMP_DOC_DIR@",
- "TFM_ROOT_DIR" : "@CMAKE_SOURCE_DIR@",
+ "TFM_ROOT_DIR" : "@CMAKE_SOURCE_DIR@/..",
"PLANTUML_JAR_PATH" : "@PLANTUML_JAR_PATH@",
"Java_JAVA_EXECUTABLE" : "@Java_JAVA_EXECUTABLE@",
"DOXYGEN_EXECUTABLE" : "@DOXYGEN_EXECUTABLE@",
diff --git a/version.cmake b/version.cmake
new file mode 100644
index 0000000..874d87d
--- /dev/null
+++ b/version.cmake
@@ -0,0 +1,7 @@
+#-------------------------------------------------------------------------------
+# Copyright (c) 2021, Arm Limited. All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+#
+#-------------------------------------------------------------------------------
+set(TFM_VERSION 1.4.0)
