Docs: Clean and simplify building scripts
Signed-off-by: Anton Komlev <anton.komlev@arm.com>
Change-Id: I97fdd3ff765ebc0c74ddf34b621b524aaf55f38e
diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
index 02ee72f..352f415 100644
--- a/docs/CMakeLists.txt
+++ b/docs/CMakeLists.txt
@@ -11,21 +11,13 @@
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 m2r2 sphinx-rtd-theme sphinxcontrib.plantuml)
-find_package(PlantUML)
find_package(Doxygen 1.8.0)
find_package(LATEX COMPONENTS PDFLATEX)
################################## ENV #########################################
-include(../cmake/version.cmake)
-
-project("Trusted Firmware M. Documentation" VERSION ${TFM_VERSION} LANGUAGES)
+project("Trusted Firmware M. Documentation" LANGUAGES)
set(SPHINXCFG_SOURCE_PATH ${CMAKE_CURRENT_SOURCE_DIR})
set(SPHINXCFG_CONFIG_PATH ${CMAKE_CURRENT_SOURCE_DIR})
@@ -39,70 +31,60 @@
################################## SPHINX ######################################
-if (SPHINX_FOUND AND PLANTUML_FOUND AND PY_M2R2_FOUND AND PY_SPHINX-RTD-THEME_FOUND AND PY_SPHINXCONTRIB.PLANTUML)
+file(GLOB_RECURSE SPHINXCFG_DOC_FILES ${SPHINXCFG_SOURCE_PATH}/*.rst ${SPHINXCFG_SOURCE_PATH}/*.md)
- file(GLOB_RECURSE SPHINXCFG_DOC_FILES ${SPHINXCFG_SOURCE_PATH}/*.rst)
+add_custom_target(tfm_docs_userguide_html ALL
+ COMMAND "${SPHINX_EXECUTABLE}" -W -b html -j auto -c ${SPHINXCFG_CONFIG_PATH} ${SPHINXCFG_SOURCE_PATH} "${SPHINXCFG_OUTPUT_PATH}/html"
+ WORKING_DIRECTORY ${SPHINXCFG_SOURCE_PATH}
+ DEPENDS ${SPHINXCFG_DOC_FILES}
+)
+add_dependencies(docs tfm_docs_userguide_html)
- add_custom_target(tfm_docs_userguide_html ALL
- COMMAND "${SPHINX_EXECUTABLE}" -W -b html -j auto -c ${SPHINXCFG_CONFIG_PATH} ${SPHINXCFG_SOURCE_PATH} "${SPHINXCFG_OUTPUT_PATH}/html"
- WORKING_DIRECTORY ${SPHINXCFG_SOURCE_PATH}
- DEPENDS ${SPHINXCFG_DOC_FILES}
- )
-
- 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()
+add_custom_command(OUTPUT "${SPHINXCFG_OUTPUT_PATH}/latex/TF-M.tex"
+ OUTPUT "${SPHINXCFG_OUTPUT_PATH}/latex/"
+ COMMAND "${SPHINX_EXECUTABLE}" -b latex "${SPHINXCFG_SOURCE_PATH}" "${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)
################################## DOXYGEN #####################################
-if (DOXYGEN_FOUND AND DOXYGEN_DOT_FOUND AND PLANTUML_FOUND)
+configure_file(${CMAKE_SOURCE_DIR}/doxygen/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY)
+file(GLOB_RECURSE DOXYCFG_DOC_FILES ${CMAKE_SOURCE_DIR}/*.c ${CMAKE_SOURCE_DIR}/*.h)
- configure_file(${CMAKE_SOURCE_DIR}/doxygen/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY)
- 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 ALL
+ WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
+ DEPENDS ${DOXYCFG_OUTPUT_PATH}/html
+)
+add_dependencies(docs tfm_docs_refman_html)
- 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 ALL
- WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
- DEPENDS ${DOXYCFG_OUTPUT_PATH}/html
- )
- add_dependencies(docs tfm_docs_refman_html)
+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)
- 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/cmake/FindPlantUML.cmake b/docs/cmake/FindPlantUML.cmake
deleted file mode 100644
index 82df16c..0000000
--- a/docs/cmake/FindPlantUML.cmake
+++ /dev/null
@@ -1,63 +0,0 @@
-#-------------------------------------------------------------------------------
-# Copyright (c) 2018-2019, Arm Limited. All rights reserved.
-#
-# SPDX-License-Identifier: BSD-3-Clause
-#
-#-------------------------------------------------------------------------------
-
-#FindPlantuml
-#-----------
-#PlantUML is a diagram generation tool. It can generate various UML and non-UML
-#diagrams. See: http://plantuml.com/
-#
-#This module checks PlantUML availability and checks if the Java runtime is
-#available.
-#For Windows PlantUML is distributed as a jar archive and thus there is no
-#standard install location where it could be searched for.
-#Most Linux distributions come with a proper PlantUML package which installs
-#a shell script to easy starting PlantUML, but the location of the .jar file
-#is hidden.
-#Thus there is no standard location to search for the .jar file and this module
-#depends on user input.
-#
-#This module has the following parameters:
-# PLANTUML_JAR_PATH = variable specifying where the PlantUML java archive
-# (plantuml.jar) can be found. If it is not defined,
-# the environment variable with the same name is used.
-# If both is missing, that is an error.
-#
-#This module defines the following variables:
-# PLANTUML_VERSION = The version reported by "plantuml.jar -version"
-# PLANTUML_FOUND = Was the .jar file found and sucesfuly executed.
-#
-
-include(Utils)
-
-find_package(Java 1.8 COMPONENTS Runtime)
-if(Java_Runtime_FOUND)
- #Check if the jar file is at the user defined location.
- #Prefer the cmake variable to the environment setting.
- if (NOT DEFINED PLANTUML_JAR_PATH)
- if (DEFINED ENV{PLANTUML_JAR_PATH})
- set(PLANTUML_JAR_PATH "$ENV{PLANTUML_JAR_PATH}" CACHE STRING "PLANTUML location." )
- endif()
- endif()
-
- if (NOT DEFINED PLANTUML_JAR_PATH)
- message(STATUS "PLANTUML_JAR_PATH variable is missing, PlantUML jar location is unknown.")
- else()
- win_fix_dir_sep(PATH PLANTUML_JAR_PATH)
- #Get plantuml version
- execute_process(COMMAND "${Java_JAVA_EXECUTABLE}" "-jar" "${PLANTUML_JAR_PATH}" "-version" OUTPUT_VARIABLE _PLANTUML_VERSION OUTPUT_STRIP_TRAILING_WHITESPACE ERROR_QUIET)
- #Parse plantuml output
- if(_PLANTUML_VERSION)
- if(_PLANTUML_VERSION MATCHES ".*PlantUML version ([0-9.]+).*")
- string(REGEX REPLACE ".*PlantUML version ([0-9.]+).*" "\\1" PLANTUML_VERSION "${_PLANTUML_VERSION}")
- endif()
- endif()
- endif()
-endif()
-
-#Set "standard" find module return values
-include(FindPackageHandleStandardArgs)
-find_package_handle_standard_args(Plantuml REQUIRED_VARS PLANTUML_JAR_PATH PLANTUML_VERSION VERSION_VAR PLANTUML_VERSION)
diff --git a/docs/cmake/FindPythonModules.cmake b/docs/cmake/FindPythonModules.cmake
deleted file mode 100644
index 6f889c6..0000000
--- a/docs/cmake/FindPythonModules.cmake
+++ /dev/null
@@ -1,64 +0,0 @@
-#-------------------------------------------------------------------------------
-# Copyright (c) 2019, Arm Limited. All rights reserved.
-#
-# SPDX-License-Identifier: BSD-3-Clause
-#
-#-------------------------------------------------------------------------------
-
-#FindPythonModules
-#-----------
-#This module checks availability of Python modules.
-#
-#This module has the following parameters:
-# PYTHON_EXECUTABLE - Location of python interpreter.
-# COMPONENTS - List of python modules to look for.
-#
-#This module defines the following variables:
-# PY_XXX - Cached string variable with the location of the module.
-# PY_XXX_FOUND - Set if the module is available.
-#
-# Where XXX is the upper case name of the module.
-#
-#Examples
-# To look for m2r and report error if not found
-# find_module(PythonModules COMPONENTS m2r)
-# if (PY_M2R_FOUND)
-# do something
-# endif()
-#
-# To look for m2r and do not report error if not found
-# find_module(PythonModules OPTIONAL_COMPONENTS m2r)
-# if (PY_M2R_FOUND)
-# do something
-# endif()
-
-if(NOT DEFINED PYTHON_EXECUTABLE)
- message(FATAL_ERROR "FindPythonModules: mandatory parameter PYTHON_EXECUTABLE is missing.")
-endif()
-
-include(Utils)
-
-foreach(_mod ${PythonModules_FIND_COMPONENTS})
- string(TOUPPER ${_mod} _mod_upper)
- string(REPLACE "-" "_" _modname "${_mod}")
- if (NOT PY_${_mod_upper})
- #Execute python and try to include the module.
- execute_process(
- COMMAND ${PYTHON_EXECUTABLE} -c "import ${_modname}; print(${_modname}.__file__);"
- RESULT_VARIABLE ${_mod}_status
- OUTPUT_VARIABLE ${_mod}_path
- ERROR_QUIET
- OUTPUT_STRIP_TRAILING_WHITESPACE)
- #If suceeded
- if(NOT ${_mod}_status)
- #Avoid trouble with directory separator on windows.
- win_fix_dir_sep(PATH ${_mod}_path)
- set("PY_${_mod_upper}" "${${_mod}_path}" CACHE STRING
- "Location of Python module ${_mod}")
- endif()
- endif()
- find_package_handle_standard_args(PY_${_mod_upper}
- FOUND_VAR PY_${_mod_upper}_FOUND
- REQUIRED_VARS PY_${_mod_upper}
- FAIL_MESSAGE "Can not find Python module ${_mod}")
-endforeach()
diff --git a/docs/cmake/Utils.cmake b/docs/cmake/Utils.cmake
deleted file mode 100644
index f422895..0000000
--- a/docs/cmake/Utils.cmake
+++ /dev/null
@@ -1,58 +0,0 @@
-#-------------------------------------------------------------------------------
-# Copyright (c) 2017-2019, Arm Limited. All rights reserved.
-#
-# SPDX-License-Identifier: BSD-3-Clause
-#
-#-------------------------------------------------------------------------------
-
-
-#Print a message and exit with failure
-#
-#Examples:
-# failure("Something is wrong!")
-
-function(failure)
- message(FATAL_ERROR "${ARGN}")
-endfunction()
-
-#Convert \ directory separators to / on windows systems
-#
-#Convert the directory separators to forward slash on windows. Avoid
-#conversion if path contains any forward slashes to avoid mixing up cygwin or
-#mingw paths where an extra caharacter is escaped (i.e. "/c/Program\ Files/")
-#
-#Examples:
-# set(MY_PATH "C:\foo\bar")
-# win_fix_dir_sep(PATH MY_PATH)
-#
-#INPUTS:
-# PATH - (mandatory) - name of the string variable to operate on
-#
-#OUTPUTS
-# PATH is modified as needed.
-#
-function(win_fix_dir_sep)
- #Parse our arguments
- set( _OPTIONS_ARGS ) #No option (on/off) arguments (e.g. IGNORE_CASE)
- set( _ONE_VALUE_ARGS PATH ) #Single option arguments (e.g. PATH "./foo/bar")
- set( _MULTI_VALUE_ARGS ) #List arguments (e.g. LANGUAGES C ASM CXX)
- cmake_parse_arguments(_MY_PARAMS "${_OPTIONS_ARGS}" "${_ONE_VALUE_ARGS}" "${_MULTI_VALUE_ARGS}" ${ARGN} )
-
- #Check mandatory parameters
- if(NOT _MY_PARAMS_PATH)
- failure("win_fix_dir_sep(): Missing mandatory parameter PATH!")
- endif()
- set(_PATH ${_MY_PARAMS_PATH})
-
- #To avoid trouble on windows change directory separator.
- if (CMAKE_HOST_SYSTEM_NAME STREQUAL "Windows")
- #Do not convert directory separator if there are forward slashes
- #present. This is to avoid mixing up escaped characters in cygwin
- #or mingw paths (i.e. c:/Program\ Files/something)
- string(FIND "${${_PATH}}" "/" _is_found)
- if (_is_found LESS 0)
- string(REPLACE "\\" "/" ${_PATH} "${${_PATH}}")
- set(${_PATH} "${${_PATH}}" PARENT_SCOPE)
- endif()
- endif()
-endfunction()
diff --git a/docs/conf.py b/docs/conf.py
index 93912b3..701419e 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -43,13 +43,6 @@
# -- General configuration ---------------------------------------------------
-# If your documentation needs a minimal Sphinx version, state it here.
-#
-# needs_sphinx = '1.4'
-
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
extensions = [
'sphinx.ext.imgmath',
'm2r2', #Support markdown files. Needed for external code.
@@ -62,9 +55,9 @@
# PlantUML
plantuml = 'java -jar ' + os.environ['PLANTUML_JAR_PATH']
-#Make auso section labals generated be prefixed with file name.
+# Make auto section labels generated be prefixed with file name.
autosectionlabel_prefix_document=True
-#Add auso section label for level 2 headers only.
+# Add auto section label for level 2 headers only.
autosectionlabel_maxdepth=2
# Add any paths that contain templates here, relative to this directory.
@@ -97,19 +90,12 @@
# -- Options for HTML output -------------------------------------------------
-# The theme to use for HTML and HTML Help pages. See the documentation for
-# a list of builtin themes.
-#
html_theme = 'sphinx_rtd_theme'
-# Theme options are theme-specific and customize the look and feel of a theme
-# further. For a list of options available for each theme, see the
-# documentation.
-#
html_theme_options = {
'collapse_navigation' : False,
'prev_next_buttons_location' : None, # Hide Prev and Next buttons
-# 'display_version': True, # Show version under logo
+ 'display_version': True, # Show version under logo
'sticky_navigation': True,
'navigation_depth': 2,
}
@@ -117,7 +103,6 @@
# Remove the "View page source" link from the top of docs pages
html_show_sourcelink = False
-#
# Add any paths that contain custom static files (such as style sheets) here,
# relative to configuration directory. They are copied after the builtin static
# files, so a file named "default.css" will overwrite the builtin "default.css".
@@ -129,16 +114,6 @@
# Set the documentation favicon
html_favicon = '_static/images/favicon.ico'
-# Custom sidebar templates, must be a dictionary that maps document names
-# to template names.
-#
-# The default sidebars (for documents that don't match any pattern) are
-# defined by theme itself. Builtin themes are using these templates by
-# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
-# 'searchbox.html']``.
-#
-# html_sidebars = {}
-
#Disable adding conf.py copyright notice to HTML output
html_show_copyright = False
@@ -155,10 +130,6 @@
# Output file base name for HTML help builder.
htmlhelp_basename = 'TF-M doc'
-rst_prolog = """
-.. |TFM_VERSION| replace:: version
-"""
-
# Enable figures and tables auto numbering
numfig = True
numfig_secnum_depth = 0
@@ -172,20 +143,9 @@
# -- Options for LaTeX output ------------------------------------------------
latex_elements = {
- # The paper size ('letterpaper' or 'a4paper').
- #
# 'papersize': 'letterpaper',
-
- # The font size ('10pt', '11pt' or '12pt').
- #
# 'pointsize': '10pt',
-
- # Additional stuff for the LaTeX preamble.
- #
# 'preamble': '',
-
- # Latex figure (float) alignment
- #
# 'figure_align': 'htbp',
}
@@ -197,24 +157,3 @@
author, 'manual'),
]
-# -- Options for manual page output ------------------------------------------
-
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
-#man_pages = [
-# (master_doc, 'tf-m', title,
-# [author], 7)
-#]
-
-# -- Options for Texinfo output ----------------------------------------------
-
-# Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-# dir menu entry, description, category)
-#texinfo_documents = [
-# (master_doc, 'TF-M', title,
-# author, 'TF-M', 'Trusted Firmware for Cortex-M',
-# 'Miscellaneous'),
-#]
-
-# -- Extension configuration -------------------------------------------------
diff --git a/docs/releases/1.0.rst b/docs/releases/1.0.rst
index 6c4143a..8bff022 100644
--- a/docs/releases/1.0.rst
+++ b/docs/releases/1.0.rst
@@ -1,4 +1,5 @@
:orphan:
+
***********
Version 1.0
***********
diff --git a/docs/releases/1.1.rst b/docs/releases/1.1.rst
index 1b4c22e..7565b9e 100644
--- a/docs/releases/1.1.rst
+++ b/docs/releases/1.1.rst
@@ -1,4 +1,5 @@
:orphan:
+
***********
Version 1.1
***********
diff --git a/docs/releases/1.2.0.rst b/docs/releases/1.2.0.rst
index d497201..2b61d12 100644
--- a/docs/releases/1.2.0.rst
+++ b/docs/releases/1.2.0.rst
@@ -1,4 +1,5 @@
:orphan:
+
*************
Version 1.2.0
*************
diff --git a/docs/releases/1.3.0.rst b/docs/releases/1.3.0.rst
index 592427b..fe05e3c 100644
--- a/docs/releases/1.3.0.rst
+++ b/docs/releases/1.3.0.rst
@@ -1,4 +1,5 @@
:orphan:
+
*************
Version 1.3.0
*************