diff options
Diffstat (limited to 'cmake')
-rw-r--r-- | cmake/Common/BuildSphinxDoc.cmake | 78 | ||||
-rw-r--r-- | cmake/SphinxCopyDoc.cmake | 65 | ||||
-rw-r--r-- | cmake/SphinxDesignDocStatus.cmake | 242 |
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() |