Build: Convert docs directory to modern cmake
Add cmake files to docs directory. Remove unneeded cmake files.
By default, the targets are generated but not run by `make all` or
`make`. The documentation can be generated by running `make docs`
Please refer to the tfm_build_instructions document for
reference examples.
WARNING: This change will not build in isolation, it requires _all_
other cmake changes to successfully build. It is split out only for ease
of understanding.
Change-Id: I1b004a8f8ccfba2df901d91b093576fdc6bfa40d
Signed-off-by: Minos Galanakis <minos.galanakis@arm.com>
Signed-off-by: Raef Coles <raef.coles@arm.com>
diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
new file mode 100644
index 0000000..f227c6e
--- /dev/null
+++ b/docs/CMakeLists.txt
@@ -0,0 +1,118 @@
+#-------------------------------------------------------------------------------
+# Copyright (c) 2020, Arm Limited. All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+#
+#-------------------------------------------------------------------------------
+
+cmake_minimum_required(VERSION 3.13)
+
+add_custom_target(docs)
+
+find_package(Python3)
+find_package(Sphinx)
+find_package(PythonModules COMPONENTS m2r sphinx-rtd-theme sphinxcontrib.plantuml)
+find_package(PlantUML)
+find_package(Doxygen 1.8.0)
+find_package(LATEX COMPONENTS PDFLATEX)
+
+################################## ENV #########################################
+
+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")
+set(DOXYCFG_OUTPUT_PATH ${CMAKE_CURRENT_BINARY_DIR}/reference_manual)
+set(DOXYCFG_DOXYGEN_CFG_DIR ${CMAKE_SOURCE_DIR}/doxygen)
+
+# Enable to request the interface to build the doxygen documentation as well
+set(DOXYCFG_DOXYGEN_BUILD False)
+
+################################## SPHINX ######################################
+set(SPHINXCFG_COPY_FILES True)
+set(SPHINXCFG_RENDER_CONF True)
+
+add_custom_target(tfm_docs_sphinx_cfg
+ DEPENDS ${SPHINX_TMP_DOC_DIR}/conf.py
+)
+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}/build_docs/conf.py ${SPHINX_TMP_DOC_DIR}/conf.py
+ MAIN_DEPENDENCY ${CMAKE_SOURCE_DIR}/build_docs/conf.py
+ BYPRODUCTS ${SPHINX_TMP_DOC_DIR}
+)
+
+configure_file(${CMAKE_CURRENT_SOURCE_DIR}/tfm_env.py.in ${SPHINX_TMP_DOC_DIR}/tfm_env.py @ONLY)
+
+if (SPHINX_FOUND AND PLANTUML_FOUND AND PY_M2R_FOUND AND PY_SPHINX-RTD-THEME_FOUND AND PY_SPHINXCONTRIB.PLANTUML)
+
+ file(GLOB_RECURSE SPHINXCFG_DOC_FILES ${CMAKE_CURRENT_SOURCE_DIR}/*.rst)
+
+ add_custom_command(OUTPUT "${SPHINXCFG_OUTPUT_PATH}/html/index.html"
+ OUTPUT "${SPHINXCFG_OUTPUT_PATH}/html/"
+ COMMAND "${SPHINX_EXECUTABLE}" -b html "${SPHINX_TMP_DOC_DIR}" "${SPHINXCFG_OUTPUT_PATH}/html"
+ WORKING_DIRECTORY "${CMAKE_SOURCE_DIR}"
+ DEPENDS tfm_docs_sphinx_cfg
+ DEPENDS ${SPHINXCFG_DOC_FILES}
+ )
+ add_custom_target(tfm_docs_userguide_html
+ DEPENDS "${SPHINXCFG_OUTPUT_PATH}/html/index.html"
+ DEPENDS "${SPHINXCFG_OUTPUT_PATH}/html/"
+ )
+ add_dependencies(docs tfm_docs_userguide_html)
+
+ if (LATEX_PDFLATEX_FOUND)
+ add_custom_command(OUTPUT "${SPHINXCFG_OUTPUT_PATH}/latex/TF-M.tex"
+ OUTPUT "${SPHINXCFG_OUTPUT_PATH}/latex/"
+ COMMAND "${SPHINX_EXECUTABLE}" -b latex "${SPHINX_TMP_DOC_DIR}" "${SPHINXCFG_OUTPUT_PATH}/latex"
+ WORKING_DIRECTORY "${CMAKE_SOURCE_DIR}"
+ DEPENDS tfm_docs_sphinx_cfg
+ DEPENDS ${SPHINXCFG_DOC_FILES}
+ )
+ add_custom_command(OUTPUT "${SPHINXCFG_OUTPUT_PATH}/latex/TF-M.pdf"
+ COMMAND ${PDFLATEX_COMPILER} TF-M.tex
+ COMMAND ${CMAKE_COMMAND} -E copy TF-M.tex ${SPHINXCFG_OUTPUT_PATH}/tf-m_user_guide.pdf
+ WORKING_DIRECTORY ${SPHINXCFG_OUTPUT_PATH}/latex/
+ DEPENDS "${SPHINXCFG_OUTPUT_PATH}/latex/TF-M.tex"
+ )
+ add_custom_target(tfm_docs_userguide_pdf
+ DEPENDS "${SPHINXCFG_OUTPUT_PATH}/latex/TF-M.pdf"
+ )
+ add_dependencies(docs tfm_docs_userguide_pdf)
+ endif()
+endif()
+
+################################## DOXYGEN #####################################
+
+configure_file(${CMAKE_SOURCE_DIR}/doxygen/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY)
+
+if (DOXYGEN_FOUND AND DOXYGEN_DOT_FOUND AND PLANTUML_FOUND)
+
+ file(GLOB_RECURSE DOXYCFG_DOC_FILES ${CMAKE_SOURCE_DIR}/*.c ${CMAKE_SOURCE_DIR}/*.h)
+
+ add_custom_command(OUTPUT ${DOXYCFG_OUTPUT_PATH}/html
+ OUTPUT ${DOXYCFG_OUTPUT_PATH}/latex
+ OUTPUT ${DOXYCFG_OUTPUT_PATH}/latex/refman.pdf
+ COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
+ WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
+ DEPENDS ${DOXYCFG_DOC_FILES}
+ )
+ add_custom_target(tfm_docs_refman_html
+ WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
+ DEPENDS ${DOXYCFG_OUTPUT_PATH}/html
+ )
+ add_dependencies(docs tfm_docs_refman_html)
+
+ if (LATEX_PDFLATEX_FOUND)
+ add_custom_command(OUTPUT "${DOXYCFG_OUTPUT_PATH}/latex/refman.pdf"
+ COMMAND "${PDFLATEX_COMPILER} refman.tex"
+ COMMAND ${CMAKE_COMMAND} -E copy refman.tex ${DOXYCFG_OUTPUT_PATH}/tf-m_reference_manual.pdf
+ WORKING_DIRECTORY ${DOXYCFG_OUTPUT_PATH}/latex/
+ DEPENDS "${DOXYCFG_OUTPUT_PATH}/latex/refman.tex"
+ )
+ add_custom_target(tfm_docs_refman_pdf
+ DEPENDS ${DOXYCFG_OUTPUT_PATH}/latex/refman.pdf
+ DEPENDS tfm_docs_refman_html
+ )
+ add_dependencies(docs tfm_docs_refman_pdf)
+ endif()
+endif()
diff --git a/docs/getting_started/tfm_build_instruction.rst b/docs/getting_started/tfm_build_instruction.rst
index a8e890b..2fb81c4 100644
--- a/docs/getting_started/tfm_build_instruction.rst
+++ b/docs/getting_started/tfm_build_instruction.rst
@@ -188,8 +188,8 @@
Using the CMake build-system
----------------------------
-Building PDF output is optional and can be disabled by removing LaTex from the
-PATH.
+Building PDF output can be requested by invoking `tfm_docs_userguide_pdf/
+tfm_docs_userguide_pdf`
.. Note::
For building the documentation all tools needed to build the firmware must
@@ -202,12 +202,13 @@
cd <TF-M base folder>
mkdir cmake_doc
cd cmake_doc
- cmake ../ -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=GNUARM
- cmake --build ./ -- install_doc
+ cmake -S .. -B . -G "Unix Makefiles" -DTFM_PLATFORM=mps2/an521 -DCMAKE_TOOLCHAIN_FILE=../toolchain_GNUARM.cmake
+ make tfm_docs_refman_html
+ make tfm_docs_refman_pdf
The documentation files will be available under the directory::
- cmake_doc/install/doc/reference_manual
+ cmake_doc/docs/reference_manual
Building the User Guide
^^^^^^^^^^^^^^^^^^^^^^^
@@ -216,12 +217,13 @@
cd <TF-M base folder>
mkdir cmake_doc
cd cmake_doc
- cmake ../ -G"Unix Makefiles" -DTARGET_PLATFORM=AN521 -DCOMPILER=ARMCLANG
- cmake --build ./ -- install_userguide
+ cmake -S .. -B . -G "Unix Makefiles" -DTFM_PLATFORM=mps2/an521 -DCMAKE_TOOLCHAIN_FILE=../toolchain_GNUARM.cmake
+ make tfm_docs_userguide_html
+ make tfm_docs_userguide_pdf
The documentation files will be available under the directory::
- cmake_doc/install/doc/user_guide
+ cmake_doc/docs/user_guide
Manually using documentation generation tools
---------------------------------------------
diff --git a/docs/tfm_env.py.in b/docs/tfm_env.py.in
index b96be48..cc2f8bf 100644
--- a/docs/tfm_env.py.in
+++ b/docs/tfm_env.py.in
@@ -8,21 +8,18 @@
# 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@"
+cmake_env = { "SPHINX_TMP_DOC_DIR" : "@SPHINX_TMP_DOC_DIR@",
+ "TFM_ROOT_DIR" : "@CMAKE_SOURCE_DIR@",
+ "PLANTUML_JAR_PATH" : "@PLANTUML_JAR_PATH@",
+ "Java_JAVA_EXECUTABLE" : "@Java_JAVA_EXECUTABLE@",
+ "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@",
+ "SPHINXCFG_TEMPLATE_FILE" : "@SPHINXCFG_TEMPLATE_FILE@",
+ "SPHINXCFG_COPY_FILES" : "@SPHINXCFG_COPY_FILES@",
+ "SPHINXCFG_RENDER_CONF" : "@SPHINXCFG_RENDER_CONF@",
+ "SPHINXCFG_TFM_VERSION" : "v@CMAKE_PROJECT_VERSION@",
+ "SPHINXCFG_TFM_VERSION_FULL" : "Version @CMAKE_PROJECT_VERSION@"
}