diff options
author | Minos Galanakis <minos.galanakis@arm.com> | 2020-07-21 15:13:52 +0100 |
---|---|---|
committer | Tamas Ban <tamas.ban@arm.com> | 2020-09-24 12:49:54 +0000 |
commit | dff2eaee4ab96f9641d7bc91b4f8ceee229d5728 (patch) | |
tree | b03fed4d75144655d893b23947aef7770fe66b39 /docs | |
parent | d19a19f161148b97f3ec8ccec7baebd79599f8c4 (diff) | |
download | trusted-firmware-m-dff2eaee4ab96f9641d7bc91b4f8ceee229d5728.tar.gz |
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>
Diffstat (limited to 'docs')
-rw-r--r-- | docs/CMakeLists.txt | 118 | ||||
-rw-r--r-- | docs/getting_started/tfm_build_instruction.rst | 18 | ||||
-rw-r--r-- | docs/tfm_env.py.in | 31 |
3 files changed, 142 insertions, 25 deletions
diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt new file mode 100644 index 0000000000..f227c6e6b2 --- /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 a8e890b63c..2fb81c4179 100644 --- a/docs/getting_started/tfm_build_instruction.rst +++ b/docs/getting_started/tfm_build_instruction.rst @@ -188,8 +188,8 @@ There are currently two ways of building the documentation: 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 @@ Building the Reference Manual 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 @@ Building the User Guide 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 b96be484d6..cc2f8bf3a2 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@" } |