aboutsummaryrefslogtreecommitdiff
path: root/cmake
diff options
context:
space:
mode:
Diffstat (limited to 'cmake')
-rw-r--r--cmake/Common/BuildSphinxDoc.cmake78
-rw-r--r--cmake/SphinxCopyDoc.cmake65
-rw-r--r--cmake/SphinxDesignDocStatus.cmake242
3 files changed, 39 insertions, 346 deletions
diff --git a/cmake/Common/BuildSphinxDoc.cmake b/cmake/Common/BuildSphinxDoc.cmake
index ab08319c3c..e95a9277b2 100644
--- a/cmake/Common/BuildSphinxDoc.cmake
+++ b/cmake/Common/BuildSphinxDoc.cmake
@@ -72,14 +72,28 @@ if (NOT SPHINX_NODOC)
set(SPHINXCFG_OUTPUT_PATH "${CMAKE_CURRENT_BINARY_DIR}/doc_sphinx")
set(SPHINX_TMP_DOC_DIR "${CMAKE_CURRENT_BINARY_DIR}/doc_sphinx_in")
-
+ set(SPHINXCFG_CONFIGURED_FILE "${TFM_ROOT_DIR}/build_docs/conf.py")
set(SPHINXCFG_TEMPLATE_FILE "${TFM_ROOT_DIR}/docs/conf.py.in")
- set(SPHINXCFG_CONFIGURED_FILE "${SPHINXCFG_OUTPUT_PATH}/conf.py")
-
- set(SPHINX_DESIGN_DOC_ROOT "${TFM_ROOT_DIR}/docs/design_documents")
- set(SPHINX_TEMPLATE_INDEX_FILE "${SPHINX_DESIGN_DOC_ROOT}/index.rst.in")
- set(SPHINX_CONFIGURED_INDEX_FILE "${SPHINX_TMP_DOC_DIR}/docs/design_documents/index.rst")
- set(SPHINX_MAIN_INDEX_FILE "docs/index.rst")
+ set(SPHINXCFG_ENVIRONMENT_FILE "${TFM_ROOT_DIR}/docs/tfm_env.py.in")
+ set(_PDF_FILE "${SPHINXCFG_OUTPUT_PATH}/latex/TF-M.pdf")
+
+ # Set the build-tool to copy over the files to ${SPHINX_TMP_DOC_DIR~
+ set(SPHINXCFG_COPY_FILES True)
+ # Set the config to render the conf.py. If needed to build it by cmake
+ # set it to False
+ set(SPHINXCFG_RENDER_CONF True)
+
+ # TODO Reference example on how a doxygen build can be requested.
+ # Currently the logic of BuildDoxygenDoc.cmake is still used for
+ # compatibility purposes.
+ set(DOXYCFG_DOXYGEN_BUILD False)
+ if (SPHINXCFG_RENDER_CONF)
+ find_package(Doxygen 1.8.0)
+ set(DOXYCFG_DOXYGEN_CFG_DIR ${TFM_ROOT_DIR}/doxygen)
+ set(DOXYCFG_OUTPUT_PATH ${SPHINXCFG_OUTPUT_PATH}/user_manual)
+ set(DOXYCFG_ECLIPSE_DOCID "org.arm.tf-m-refman")
+ file(MAKE_DIRECTORY ${SPHINXCFG_OUTPUT_PATH}/user_manual)
+ endif()
#Version ID of TF-M.
#TODO: this shall not be hard-coded here. We need a process to define the
@@ -87,44 +101,26 @@ if (NOT SPHINX_NODOC)
set(SPHINXCFG_TFM_VERSION "v1.1")
set(SPHINXCFG_TFM_VERSION_FULL "Version 1.1")
- get_filename_component(_NDX_FILE_DIR ${SPHINX_CONFIGURED_INDEX_FILE} DIRECTORY )
-
#This command does not generates the specified output file and thus it will
#always be run. Any other command or target depending on the "run-allways"
#output will be always executed too.
add_custom_command(OUTPUT run-allways
COMMAND "${CMAKE_COMMAND}" -E echo)
- #Using add_custom_command allows CMake to generate proper clean commands
- #for document generation.
- add_custom_command(OUTPUT "${SPHINX_TMP_DOC_DIR}"
- "${SPHINX_CONFIGURED_INDEX_FILE}"
- #Create target directory for SPHINX_CONFIGURED_INDEX_FILE. Needed
- #by the next command.
- COMMAND "${CMAKE_COMMAND}" -E make_directory "${_NDX_FILE_DIR}"
- #Fill out index.rst template
- COMMAND "${CMAKE_COMMAND}" -D TFM_ROOT_DIR=${TFM_ROOT_DIR}
- -D SPHINX_TEMPLATE_INDEX_FILE=${SPHINX_TEMPLATE_INDEX_FILE}
- -D SPHINX_CONFIGURED_INDEX_FILE=${SPHINX_CONFIGURED_INDEX_FILE}
- -D SPHINX_DESIGN_DOC_ROOT=${SPHINX_DESIGN_DOC_ROOT}
- -P "${TFM_ROOT_DIR}/cmake/SphinxDesignDocStatus.cmake"
- #Copy document files to temp direcotry
- COMMAND "${CMAKE_COMMAND}" -D TFM_ROOT_DIR=${TFM_ROOT_DIR}
- -D DST_DIR=${SPHINX_TMP_DOC_DIR}
- -D BINARY_DIR=${CMAKE_BINARY_DIR}
- -D MASTER_IDX=${SPHINX_MAIN_INDEX_FILE}
- -P "${TFM_ROOT_DIR}/cmake/SphinxCopyDoc.cmake"
- WORKING_DIRECTORY "${TFM_ROOT_DIR}"
- DEPENDS run-allways
- VERBATIM
- )
+ file(REMOVE_RECURSE ${SPHINX_TMP_DOC_DIR})
+ file(MAKE_DIRECTORY ${SPHINX_TMP_DOC_DIR})
+
+ #Call configure file to fill out the message template.
+ configure_file("${SPHINXCFG_ENVIRONMENT_FILE}" "${SPHINX_TMP_DOC_DIR}/tfm_env.py" @ONLY)
+
+ file(COPY "${SPHINXCFG_CONFIGURED_FILE}" DESTINATION ${SPHINX_TMP_DOC_DIR})
add_custom_target(create_sphinx_input
SOURCES "${SPHINX_TMP_DOC_DIR}"
)
add_custom_command(OUTPUT "${SPHINXCFG_OUTPUT_PATH}/html"
- COMMAND "${SPHINX_EXECUTABLE}" -c "${SPHINXCFG_OUTPUT_PATH}" -b html "${SPHINX_TMP_DOC_DIR}" "${SPHINXCFG_OUTPUT_PATH}/html"
+ COMMAND "${SPHINX_EXECUTABLE}" -b html "${SPHINX_TMP_DOC_DIR}" "${SPHINXCFG_OUTPUT_PATH}/html"
WORKING_DIRECTORY "${TFM_ROOT_DIR}"
DEPENDS create_sphinx_input run-allways
COMMENT "Running Sphinx to generate user guide (HTML)."
@@ -145,6 +141,15 @@ if (NOT SPHINX_NODOC)
PATTERN .buildinfo EXCLUDE
)
+ if (DOXYCFG_DOXYGEN_BUILD)
+ #Add the HTML documentation to install content
+ install(DIRECTORY ${SPHINXCFG_OUTPUT_PATH}/user_manual DESTINATION doc
+ EXCLUDE_FROM_ALL
+ COMPONENT user_guide
+ PATTERN .buildinfo EXCLUDE
+ )
+ endif()
+
#If PDF documentation is being made.
if (LATEX_PDFLATEX_FOUND)
if (NOT CMAKE_GENERATOR MATCHES "Makefiles")
@@ -156,10 +161,8 @@ if (NOT SPHINX_NODOC)
message(FATAL_ERROR "CMAKE_MAKE_PROGRAM is not set. This file must be included after the project command is run.")
endif()
- set(_PDF_FILE "${SPHINXCFG_OUTPUT_PATH}/latex/TF-M.pdf")
-
add_custom_command(OUTPUT "${SPHINXCFG_OUTPUT_PATH}/latex"
- COMMAND "${SPHINX_EXECUTABLE}" -c "${SPHINXCFG_OUTPUT_PATH}" -b latex "${SPHINX_TMP_DOC_DIR}" "${SPHINXCFG_OUTPUT_PATH}/latex"
+ COMMAND "${SPHINX_EXECUTABLE}" -b latex "${SPHINX_TMP_DOC_DIR}" "${SPHINXCFG_OUTPUT_PATH}/latex"
WORKING_DIRECTORY "${TFM_ROOT_DIR}"
DEPENDS create_sphinx_input
COMMENT "Running Sphinx to generate user guide (LaTeX)."
@@ -205,7 +208,4 @@ if (NOT SPHINX_NODOC)
-P "${CMAKE_BINARY_DIR}/cmake_install.cmake")
endif()
- #Now instantiate a Sphinx configuration file from the template.
- message(STATUS "Writing Sphinx configuration...")
- configure_file(${SPHINXCFG_TEMPLATE_FILE} ${SPHINXCFG_CONFIGURED_FILE} @ONLY)
endif()
diff --git a/cmake/SphinxCopyDoc.cmake b/cmake/SphinxCopyDoc.cmake
deleted file mode 100644
index 6bf2f073ad..0000000000
--- a/cmake/SphinxCopyDoc.cmake
+++ /dev/null
@@ -1,65 +0,0 @@
-#-------------------------------------------------------------------------------
-# Copyright (c) 2019, Arm Limited. All rights reserved.
-#
-# SPDX-License-Identifier: BSD-3-Clause
-#
-#-------------------------------------------------------------------------------
-
-#Sphinx needs all document files to be under a single directory. This script
-#copies all document files to a temporary directory while keeping the original
-#directory tree (relative location of files) except "docs/index.rst" which is
-#moved to the top level of the new tree.
-#
-# i.e.:
-# <DST_DIR>
-# | All documents from <TFM_ROOT_DIR> plus <TFM_ROOT_DIR>/docs/index.rst
-# |
-# +---docs
-# | |
-# \- all documents from <TFM_ROOT_DIR>/docs except index.rst
-# |
-# +---lib
-# | |
-# | \- All document from <TFM_ROOT_DIR>/lib keeping reativle location
-# ...
-# |
-#
-#Usage:
-# cmake -DDST_DIR=<path to destination> -DTFM_ROOT_DIR=<path to tf-m root> \
-# -DBINARY_DIR=${CMAKE_BINARY_DIR}
-# -DMASTER_IDX=<path to master index.rst> -P SphinxCopyDoc.cmake
-
-#Check input parameters
-foreach(_PARAM IN ITEMS TFM_ROOT_DIR DST_DIR BINARY_DIR MASTER_IDX)
- if (NOT DEFINED ${_PARAM})
- message(FATAL_ERROR "Variable ${_PARAM} is undefined. Please add -D${_PARAM}=<...> when calling this script.")
- endif()
-endforeach()
-
-message(STATUS "Creating document tree for Sphinx under ${DST_DIR}")
-
-#List all document files.
-file(GLOB_RECURSE _COPY_FILES
- LIST_DIRECTORIES false
- RELATIVE "${TFM_ROOT_DIR}"
- "${TFM_ROOT_DIR}/*.md"
- "${TFM_ROOT_DIR}/*.rst"
- "${TFM_ROOT_DIR}/*.png"
- "${TFM_ROOT_DIR}/*.jpg"
- "${TFM_ROOT_DIR}/dco.txt")
-
-#Remove intermediate and final document build outputs.
-foreach(_PATH IN ITEMS BINARY_DIR DST_DIR)
- file(RELATIVE_PATH _REL_DIR ${TFM_ROOT_DIR} ${${_PATH}})
- list(FILTER _COPY_FILES EXCLUDE REGEX "${_REL_DIR}/.*")
-endforeach()
-
-#Copy files with directory tree.
-foreach(_FILE ${_COPY_FILES})
- get_filename_component(_DIR ${_FILE} DIRECTORY)
- if (_FILE STREQUAL MASTER_IDX)
- file(COPY ${_FILE} DESTINATION "${DST_DIR}")
- else()
- file(COPY ${_FILE} DESTINATION "${DST_DIR}/${_DIR}")
- endif()
-endforeach()
diff --git a/cmake/SphinxDesignDocStatus.cmake b/cmake/SphinxDesignDocStatus.cmake
deleted file mode 100644
index ec8279c2cb..0000000000
--- a/cmake/SphinxDesignDocStatus.cmake
+++ /dev/null
@@ -1,242 +0,0 @@
-#-------------------------------------------------------------------------------
-# Copyright (c) 2019-2020, Arm Limited. All rights reserved.
-#
-# SPDX-License-Identifier: BSD-3-Clause
-#
-#-------------------------------------------------------------------------------
-
-#A script to fill out the "toctree" file lists in index.rst.in to put design
-#documents into the correct section based on their state.
-#
-#First rst files are parsed under a defined directory, to identify document
-#status based on value of the ":Status:" field. Each state will have a list
-#being generated to which matching documents are added. These lists are used
-#then to fill template values using configure_file()
-#
-#The ":Status:" field is optional according to design proposal process.
-#Apparently, only the documents in "Accepted" status will be merged and included
-#in Sphinx build. Therefore, a design document without ":Status:" field will be
-#put in "Accepted" category by default.
-#If there are design document drafts in local environment, it is assumed that
-#developers are aware of the status of these drafts and won't be confused.
-#A message will be still thrown out when a design document doesn't contain
-#":Status:" field. It can be removed if more and more design documents don't
-#maintain that field.
-#
-#Functions are used whenever possible to avoid global variable name space
-#pollution.
-#
-
-Include(CMakeParseArguments)
-
-#Set the status value here to avoid any typo or upper/lower case trouble.
-set(ACCEPTED_STATUS "ACCEPTED")
-set(DRAFT_STATUS "DRAFT")
-set(DETAILED_STATUS "DETAILED")
-#"NO_SET" is used to mark documents without status field.
-set(NO_SET "NO_SET")
-#"INVALID_STATUS" is used to mark a document which specifies the status but the
-#status value is invalid or unrecognized.
-set(INVALID_STATUS "INVALID_STATUS")
-
-#This function will search for .rst files in a given directory, read them and
-#check if the ":Status:" field is defined in them. Then will add each file to a
-#list with a name matching the status value.
-#See the definition of _STATE_VALUES below for a list of valid state values.
-#Files without state value will be placed on the both "Accepted" list and
-#"NO_SET" list.
-#State value comparison is case insensitive.
-#
-#The output lists will have the prefix specified in the PREFIX parameter.
-#
-#Inputs:
-# DIR Directory to scan for rst files.
-# PREFIX The prefix of output list variables.
-#
-#Outputs:
-# <prefix>_<state> - list; all files with a valid state value.
-# <prefix>_NO_SET - list; all files without status field.
-# <prefix>_INVALID_STATUS - list; all files with invalid status field.
-#
-#Examples
-# sphinx_categorize_rst(DIR ${TFM_ROOT_DIR}/docs/design_documents
-# PREFIX "DESIGN_DOCS")
-#
-function(sphinx_categorize_rst)
- #Valid state values.
- set(_STATE_VALUES ${DRAFT_STATUS} ${ACCEPTED_STATUS} ${DETAILED_STATUS}
- ${NO_SET} ${INVALID_STATUS})
-
- #No option (on/off) arguments
- set( _OPTIONS_ARGS )
- #Single option arguments (e.g. PROJ_NAME "bubu_project")
- set( _ONE_VALUE_ARGS DIR PREFIX)
- #List arguments (e.g. LANGUAGES C ASM CXX)
- set( _MULTI_VALUE_ARGS )
-
- cmake_parse_arguments(_MY_PARAMS "${_OPTIONS_ARGS}" "${_ONE_VALUE_ARGS}"
- "${_MULTI_VALUE_ARGS}" ${ARGN} )
-
- #Check parameters
- foreach(_PARAM IN LISTS _ONE_VALUE_ARGS)
- if (NOT DEFINED _MY_PARAMS_${_PARAM})
- message(FATAL_ERROR "Parameter ${_PARAM} is missing!")
- endif()
- endforeach()
-
- #Search for .rst files
- file(GLOB_RECURSE _RST_FILES
- LIST_DIRECTORIES False
- ${_MY_PARAMS_DIR}/**.rst)
-
- #Loop over .rst files
- foreach(_FILE IN LISTS _RST_FILES)
- #Read the file and return the first status line.
- file(STRINGS ${_FILE} _CONTENT REGEX ":Status:" LIMIT_COUNT 1)
-
- #Nothing read -> the field is missing
- if (_CONTENT STREQUAL "")
- #If a document doesn't maintain a status field, put it in
- #Accepted list by default.
- list(APPEND _STATUS_${ACCEPTED_STATUS} ${_FILE})
- #Also add the file to the "NO_SET" list. Thus it can be
- #highlighted later.
- list(APPEND _STATUS_${NO_SET} ${_FILE})
- else()
- #convert to upper case for case insensitive matching.
- string(TOUPPER ${_CONTENT} _CONTENT)
-
- #loop over status values
- foreach(_STATUS IN LISTS _STATE_VALUES)
- #convert to upper case for case insensitive matching.
- string(TOUPPER ${_STATUS} _STATUS)
- #does status match the value from the file?
- if (_CONTENT MATCHES ":STATUS:[ ]*${_STATUS}")
- #add it to the list
- list(APPEND _STATUS_${_STATUS} ${_FILE})
- #and exit the loop
- break()
- endif()
-
- #If the status value is invalid.
- if (_STATUS STREQUAL ${INVALID_STATUS})
- list(APPEND _STATUS_${INVALID_STATUS} ${_FILE})
- endif()
- endforeach()
- endif()
- endforeach()
-
- #return the lists to the caller
- foreach(_STATUS IN LISTS _STATE_VALUES)
- string(TOUPPER ${_STATUS} _STATUS)
-
- if (DEFINED _STATUS_${_STATUS})
- set(${_MY_PARAMS_PREFIX}_${_STATUS} ${_STATUS_${_STATUS}}
- PARENT_SCOPE)
- endif()
- endforeach()
-endfunction()
-
-#Configure (fill in) the Sphinx index.rst.in template file.
-#Call sphinx_categorize_rst() to get the .rst files sorted to lists, and then
-#create the list of files for each design document section (convert the CMake
-#lists to properly formatted text).
-#Finally call configure_file() to fill in the values.
-#
-#Inputs:
-# SRC Full path to template index file
-# DST Full patch to configured output file.
-# DOC_DIR Path to design documents directory.
-# DOC_ROOT Path to root directory of documentation
-#
-#Outputs:
-# Configured <DST> file.
-#
-#Examples
-# sphinx_categorize_rst(DIR ${TFM_ROOT_DIR}/docs/design_documents
-# PREFIX "DESIGN_DOCS")
-#
-function(sphinx_configure_index)
- set(_STATE_VALUES ${DRAFT_STATUS} ${ACCEPTED_STATUS} ${DETAILED_STATUS}
- ${DEFAULT_STATUS} ${INVALID_STATUS})
-
- #No option (on/off) arguments
- set( _OPTIONS_ARGS )
- #Single option arguments (e.g. PROJ_NAME "bubu_project")
- set( _ONE_VALUE_ARGS SRC DST DOC_ROOT DOC_DIR)
- #List arguments (e.g. LANGUAGES C ASM CXX)
- set( _MULTI_VALUE_ARGS )
-
- cmake_parse_arguments(_MY_PARAMS "${_OPTIONS_ARGS}" "${_ONE_VALUE_ARGS}"
- "${_MULTI_VALUE_ARGS}" ${ARGN} )
-
- #Check parameters
- foreach(_PARAM IN LISTS _ONE_VALUE_ARGS)
- if (NOT DEFINED _MY_PARAMS_${_PARAM})
- message(FATAL_ERROR "Parameter ${_PARAM} is missing!")
- endif()
- endforeach()
-
- #Assign design documents to lists based on their status
- sphinx_categorize_rst(DIR ${_MY_PARAMS_DOC_DIR} PREFIX "_DD")
-
- #Highlight documents without status field
- if (DEFINED _DD_${NO_SET})
- string(REPLACE ";" "\n \t" _DD_${NO_SET} "${_DD_${NO_SET}}")
- message(" The following documents are put into Accepted category without status field:\n \t${_DD_${NO_SET}}")
- endif()
-
- #Look for invalid documents
- if (DEFINED _DD_${INVALID_STATUS})
- string(REPLACE ";" "\n \t" _DD_${INVALID_STATUS} "${_DD_${INVALID_STATUS}}")
- message(WARNING " The following documents provide invalid status information:\n \t${_DD_${INVALID_STATUS}}")
- endif()
-
- #The document root must be an absolute path
- get_filename_component(_MY_PARAMS_DOC_ROOT "${_MY_PARAMS_DOC_ROOT}"
- ABSOLUTE)
-
- #Loop over status lists
- foreach(_STATUS IN ITEMS ${DRAFT_STATUS} ${DETAILED_STATUS} ${ACCEPTED_STATUS})
- #Create an empty file list for this status
- set(${_STATUS}_DD_LIST "")
- #If the source list is empty go to next iteration
- if (NOT DEFINED _DD_${_STATUS})
- continue()
- endif()
-
- #Loop over files on the list of this status
- foreach(_FILE IN LISTS _DD_${_STATUS})
-
- # Strip path from the filesince index is placed in same location
- get_filename_component(_FILE ${_FILE} NAME)
- #Detailed and Draft files go to the same section
- if (_STATUS STREQUAL ${DETAILED_STATUS})
- set(_STATUS ${DRAFT_STATUS})
- endif()
-
- #Append the file to the output string
- string(APPEND ${_STATUS}_DD_LIST "\n ${_FILE}")
- endforeach()
- endforeach()
-
- #Call configure file to fill out the template.
- configure_file(${_MY_PARAMS_SRC} ${_MY_PARAMS_DST} @ONLY)
-endfunction()
-
-#If being run in script mode (cmake -P) and not included.
-if (DEFINED CMAKE_SCRIPT_MODE_FILE
- AND (CMAKE_CURRENT_LIST_FILE STREQUAL CMAKE_SCRIPT_MODE_FILE))
- #Check input variables.
- foreach(_PARAM IN ITEMS SPHINX_TEMPLATE_INDEX_FILE SPHINX_CONFIGURED_INDEX_FILE
- SPHINX_DESIGN_DOC_ROOT TFM_ROOT_DIR)
- if (NOT DEFINED ${_PARAM})
- message(FATAL_ERROR "Parameter ${_PARAM} is not set!")
- endif()
- endforeach()
-
- sphinx_configure_index(SRC ${SPHINX_TEMPLATE_INDEX_FILE}
- DST ${SPHINX_CONFIGURED_INDEX_FILE}
- DOC_DIR ${SPHINX_DESIGN_DOC_ROOT}
- DOC_ROOT ${TFM_ROOT_DIR})
-endif()