docs: Divorcing tools for the main and docs build
Change-Id: Ica15c40b54cde1cf0ae365ed80c38d2f086f6b2f
Signed-off-by: Anton Komlev <anton.komlev@arm.com>
diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
index f1a2b2d..b17780a 100644
--- a/docs/CMakeLists.txt
+++ b/docs/CMakeLists.txt
@@ -9,7 +9,7 @@
add_custom_target(docs)
-list(APPEND CMAKE_MODULE_PATH ${CMAKE_SOURCE_DIR}/../cmake)
+list(APPEND CMAKE_MODULE_PATH ${CMAKE_SOURCE_DIR}/cmake)
find_package(Python3)
find_package(Sphinx)
diff --git a/docs/cmake/FindPlantUML.cmake b/docs/cmake/FindPlantUML.cmake
new file mode 100644
index 0000000..82df16c
--- /dev/null
+++ b/docs/cmake/FindPlantUML.cmake
@@ -0,0 +1,63 @@
+#-------------------------------------------------------------------------------
+# 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
new file mode 100644
index 0000000..6f889c6
--- /dev/null
+++ b/docs/cmake/FindPythonModules.cmake
@@ -0,0 +1,64 @@
+#-------------------------------------------------------------------------------
+# 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/FindSphinx.cmake b/docs/cmake/FindSphinx.cmake
new file mode 100644
index 0000000..d390398
--- /dev/null
+++ b/docs/cmake/FindSphinx.cmake
@@ -0,0 +1,92 @@
+#-------------------------------------------------------------------------------
+# Copyright (c) 2019, Arm Limited. All rights reserved.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+#
+#-------------------------------------------------------------------------------
+
+#FindSphinx
+#-----------
+#Sphinx is a document generation tool written in Python.
+#See http://www.sphinx-doc.org/en/master/
+#
+#This module checks availability of the Sphinx document generator
+#(sphinx-build) and it's dependences (Python).
+#Sphinx is distributed as pip package or on Linux as a distribution specific
+#package (i.e. python-sphinx for Ubuntu). Independent of the distribution
+#method this module expects sphix-build to be either available on the PATH,
+#or to be located in a host OS specific standard location.
+#
+#This modules has the following parameters:
+# SPHINX_PATH = variable specifying where sphinx-build can be found.
+# If it is not defined the environment variable with
+# the same name is used. If that is also undefined,
+# then OS specific standard locations will be
+# searched.
+#
+# This modules defines the following variables:
+# SPHINX_VERSION = The version reported by "sphinx-build --version"
+# SPHINX_FOUND = True is sphinx-build was found and executed fine
+#
+
+Include(CMakeParseArguments)
+
+#Sphinx needs Python.
+find_package(PythonInterp 3)
+if (NOT PYTHONINTERP_FOUND)
+ message(STATUS "Can not find Python3.x interpreter. Pyhton3 must be installed and available on the PATH.")
+ message(STATUS "Sphinx documentation targets will not be created.")
+ return()
+endif()
+
+if (NOT DEFINED SPHINX_PATH)
+ if (DEFINED $ENV{SPHINX_PATH})
+ set(SPHINX_PATH $ENV{SPHINX_PATH})
+ endif()
+endif()
+
+
+if (DEFINED SPHINX_PATH)
+ #Find the Sphinx executable. Search only at SPHINX_PATH.
+ find_program(SPHINX_EXECUTABLE
+ NAMES sphinx-build
+ DOC "Sphinx Documentation Builder (sphinx-doc.org)"
+ PATH ${SPHINX_PATH}
+ NO_DEFAULT_PATH
+ NO_CMAKE_ENVIRONMENT_PATH
+ NO_CMAKE_PATH
+ NO_SYSTEM_ENVIRONMENT_PATH
+ NO_CMAKE_SYSTEM_PATH
+ NO_CMAKE_FIND_ROOT_PATH
+ )
+ if (SPHINX_EXECUTABLE-NOTFOUND)
+ message(STATUS "Failed to find sphinx-build at ${SPHINX_PATH}.")
+ message(STATUS "Sphinx documentation targets will not be created.")
+ return()
+ endif()
+else()
+ #Find the Sphinx executable. Search OS specific default locations.
+ find_program(SPHINX_EXECUTABLE
+ NAMES sphinx-build
+ DOC "Sphinx Documentation Builder (sphinx-doc.org)"
+ )
+
+ if (SPHINX_EXECUTABLE-NOTFOUND)
+ message(STATUS "Failed to find sphinx-build at OS specific default locations.")
+ message(STATUS "Sphinx documentation targets will not be created.")
+ return()
+ endif()
+endif()
+
+#Get Sphinx version
+execute_process(COMMAND "${SPHINX_EXECUTABLE}" "--version" OUTPUT_VARIABLE _SPHINX_VERSION OUTPUT_STRIP_TRAILING_WHITESPACE ERROR_QUIET)
+#Parse output
+if(_SPHINX_VERSION)
+ if(_SPHINX_VERSION MATCHES ".*sphinx-build[^0-9.]*([0-9.]+).*")
+ string(REGEX REPLACE ".*sphinx-build ([0-9.]+).*" "\\1" SPHINX_VERSION "${_SPHINX_VERSION}")
+ endif()
+endif()
+
+#Set "standard" find module return values
+include(FindPackageHandleStandardArgs)
+find_package_handle_standard_args(Sphinx REQUIRED_VARS SPHINX_EXECUTABLE SPHINX_VERSION VERSION_VAR SPHINX_VERSION)
diff --git a/docs/cmake/Utils.cmake b/docs/cmake/Utils.cmake
new file mode 100644
index 0000000..f422895
--- /dev/null
+++ b/docs/cmake/Utils.cmake
@@ -0,0 +1,58 @@
+#-------------------------------------------------------------------------------
+# 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/technical_references/instructions/documentation_generation.rst b/docs/technical_references/instructions/documentation_generation.rst
index 72e7e55..b8bd9ca 100644
--- a/docs/technical_references/instructions/documentation_generation.rst
+++ b/docs/technical_references/instructions/documentation_generation.rst
@@ -39,6 +39,11 @@
# For PDF generation
sudo apt-get install -y doxygen-latex
+ # Additional Python dependencies for documentation
+ pip3 install --upgrade pip
+ cd trusted-firmware-m
+ pip3 install -r tools/requirements_docs.txt
+
2. Currently, there are two ways of building TF-M reference manual:
- Using the CMake build system as custom targets
@@ -93,6 +98,11 @@
.. code-block:: bash
+ # Additional Python dependencies for documentation
+ pip3 install --upgrade pip
+ cd trusted-firmware-m
+ pip3 install -r tools\requirements_docs.txt
+
set PLANTUML_JAR_PATH=<plantuml_Path>\plantuml.jar
set PATH=$PATH;<ARM_DS_PATH>\sw\java\bin