docs: Direct documentation build
- Stop prebuilding conf.py and passing environmental info there
- Simplify CMake script for Shpinx doc generation
- Enable true incremental build for *.rst files
Signed-off-by: Anton Komlev <anton.komlev@arm.com>
Change-Id: I0c49043cda43dca263f530dde13052bcf9f49046
diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
index 69f129c..02ee72f 100644
--- a/docs/CMakeLists.txt
+++ b/docs/CMakeLists.txt
@@ -27,9 +27,10 @@
project("Trusted Firmware M. Documentation" VERSION ${TFM_VERSION} LANGUAGES)
+set(SPHINXCFG_SOURCE_PATH ${CMAKE_CURRENT_SOURCE_DIR})
+set(SPHINXCFG_CONFIG_PATH ${CMAKE_CURRENT_SOURCE_DIR})
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)
@@ -37,36 +38,17 @@
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}/conf.py ${SPHINX_TMP_DOC_DIR}/conf.py
- MAIN_DEPENDENCY ${CMAKE_SOURCE_DIR}/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_M2R2_FOUND AND PY_SPHINX-RTD-THEME_FOUND AND PY_SPHINXCONTRIB.PLANTUML)
- file(GLOB_RECURSE SPHINXCFG_DOC_FILES ${CMAKE_CURRENT_SOURCE_DIR}/*.rst)
+ file(GLOB_RECURSE SPHINXCFG_DOC_FILES ${SPHINXCFG_SOURCE_PATH}/*.rst)
- add_custom_command(OUTPUT "${SPHINXCFG_OUTPUT_PATH}/html/index.html"
- OUTPUT "${SPHINXCFG_OUTPUT_PATH}/html/"
- COMMAND "${SPHINX_EXECUTABLE}" -W -b html "${SPHINX_TMP_DOC_DIR}" "${SPHINXCFG_OUTPUT_PATH}/html"
- WORKING_DIRECTORY "${CMAKE_SOURCE_DIR}"
- DEPENDS tfm_docs_sphinx_cfg
+ 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_custom_target(tfm_docs_userguide_html ALL
- DEPENDS "${SPHINXCFG_OUTPUT_PATH}/html/index.html"
- DEPENDS "${SPHINXCFG_OUTPUT_PATH}/html/"
- )
+
add_dependencies(docs tfm_docs_userguide_html)
if (LATEX_PDFLATEX_FOUND)
@@ -92,10 +74,9 @@
################################## 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)
+ 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
diff --git a/docs/conf.py b/docs/conf.py
index 5a83618..f856fa7 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,32 +1,203 @@
-# -----------------------------------------------------------------------------
-# Copyright (c) 2020, Arm Limited. All rights reserved.
+# -*- coding: utf-8 -*-
+#-------------------------------------------------------------------------------
+# Copyright (c) 2019-2022, Arm Limited. All rights reserved.
#
# SPDX-License-Identifier: BSD-3-Clause
#
-# -----------------------------------------------------------------------------
+#-------------------------------------------------------------------------------
+
+# Configuration file for the Sphinx documentation builder.
#
-# Configuration file override for the Sphinx documentation builder.
-#
-# This file is used when Sphinx build is invoked directly at this level.
-# It will trigger a copy-files operation and render a new configuration
-# using either auto-detected or cmake provided parameters.
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
import os
import sys
+import re
+from subprocess import check_output
-# Attempt to find the tools directory by recursing up to five levels of parents
-root_path = os.path.dirname(os.path.abspath(__file__))
+# -- Project information -----------------------------------------------------
-for i in range(5):
- root_path = os.path.dirname(root_path)
- doc_path = os.path.join(root_path, "tools", "documentation")
- if os.path.isdir(doc_path):
- sys.path.insert(0, os.path.abspath(doc_path))
-sys.path.append("./")
+project = 'Trusted Firmware-M'
+copyright = '2017-2022, ARM CE-OSS'
+author = 'ARM CE-OSS'
+title = 'User Guide'
-# Trigger the copy operation logic
-import tfm_copy_files
+# -- Extract current version -------------------------------------------------
-# Import the rendered configuration into global scope
-from tfm_cmake_defaults import *
+try:
+ vrex = re.compile(r'TF-M(?P<GIT_VERSION>v.+?)'
+ r'(-[0-9]+-g)?(?P<GIT_SHA>[a-f0-9]{7,})?$')
-from conf_rendered import *
+ version = check_output("git describe --tags --always",
+ shell = True, encoding = 'UTF-8')
+
+ _v = vrex.match(version)
+ release = _v.group('GIT_VERSION')
+ if _v.group('GIT_SHA'):
+ version = release + "+" + _v.group('GIT_SHA')[:7]
+
+except:
+ version = release = 'Unknown'
+
+# -- 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.
+ 'sphinx.ext.autosectionlabel', #Make sphinx generate a label for each section
+ 'sphinxcontrib.plantuml', #Add support for PlantUML drawings
+ 'sphinxcontrib.rsvgconverter', #Add support for SVG to PDF
+ 'sphinx_tabs.tabs' #Enable tab extension in Sphinx
+]
+
+# PlantUML
+plantuml = 'java -jar ' + os.environ['PLANTUML_JAR_PATH']
+
+#Make auso section labals generated be prefixed with file name.
+autosectionlabel_prefix_document=True
+#Add auso section label for level 2 headers only.
+autosectionlabel_maxdepth=2
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+source_suffix = ['.rst', '.md']
+
+# The master toctree document.
+master_doc = 'index'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path .
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'readme.rst',
+ 'platform/ext/target/cypress/psoc64/security/keys/readme.rst',
+ 'lib/ext/**']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# -- 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}
+#
+# 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".
+html_static_path = ['_static']
+
+# Set the documentation logo relative to configuration directory
+html_logo = '_static/images/tf_logo_white.png'
+
+# 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
+
+#Add custom css for HTML. Used to allow full page width rendering
+def setup(app):
+ app.add_css_file('css/tfm_custom.css')
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# 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
+numfig_format = {
+ 'figure': 'Figure %s:',
+ 'table': 'Table %s:',
+ 'code-block': 'Listing %s:',
+ 'section': '%s'
+}
+
+# -- 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',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+# author, documentclass [howto, manual, or own class]).
+latex_documents = [
+ (master_doc, 'TF-M.tex', title,
+ 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/conf.py.in b/docs/conf.py.in
deleted file mode 100644
index 76922be..0000000
--- a/docs/conf.py.in
+++ /dev/null
@@ -1,201 +0,0 @@
-# -*- coding: utf-8 -*-
-#-------------------------------------------------------------------------------
-# Copyright (c) 2019-2022, Arm Limited. All rights reserved.
-#
-# SPDX-License-Identifier: BSD-3-Clause
-#
-#-------------------------------------------------------------------------------#
-
-# Configuration file for the Sphinx documentation builder.
-#
-# This file does only contain a selection of the most common options. For a
-# full list see the documentation:
-# http://www.sphinx-doc.org/en/master/config
-
-# -- Path setup --------------------------------------------------------------
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-import os
-import sys
-
-# -- Project information -----------------------------------------------------
-
-project = 'Trusted Firmware-M'
-copyright = '2017-2022, ARM CE-OSS'
-author = 'ARM CE-OSS'
-title = 'User Guide'
-
-# The project version in the form: "vX.Y.Z" in case of clear release
-# or "vX.Y.Z+ (latest SHA)" if an update was posted.
-version = '@SPHINXCFG_TFM_VERSION@'
-# Do not distinguish between release and version in Shpinx
-release = version
-
-
-# -- 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.
- 'sphinx.ext.autosectionlabel', #Make sphinx generate a label for each section
- 'sphinxcontrib.plantuml', #Add support for PlantUML drawings
- 'sphinxcontrib.rsvgconverter', #Add support for SVG to PDF
- 'sphinx_tabs.tabs' #Enable tab extension in Sphinx
-]
-
-#Location of PlantUML
-plantuml = '@Java_JAVA_EXECUTABLE@ -jar @PLANTUML_JAR_PATH@'
-
-#Make auso section labals generated be prefixed with file name.
-autosectionlabel_prefix_document=True
-#Add auso section label for level 2 headers only.
-autosectionlabel_maxdepth=2
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
-# The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-#
-source_suffix = ['.rst', '.md']
-
-# The master toctree document.
-master_doc = 'index'
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
-language = None
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path .
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'readme.rst',
- 'platform/ext/target/cypress/psoc64/security/keys/readme.rst',
- 'lib/ext/**']
-
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
-
-
-# -- 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}
-#
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['@TFM_ROOT_DIR@/docs/_static']
-
-# Set the documentation logo
-html_logo = '@TFM_ROOT_DIR@/docs/_static/images/tf_logo_white.png'
-
-# 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
-
-#Add custom css for HTML. Used to allow full page width rendering
-def setup(app):
- app.add_css_file('css/tfm_custom.css')
-
-# -- Options for HTMLHelp output ---------------------------------------------
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = 'TF-M doc'
-
-rst_prolog = """
-.. |TFM_VERSION| replace:: @SPHINXCFG_TFM_VERSION@
-"""
-
-# Enable figures and tables auto numbering
-numfig = True
-numfig_secnum_depth = 0
-numfig_format = {
- 'figure': 'Figure %s:',
- 'table': 'Table %s:',
- 'code-block': 'Listing %s:',
- 'section': '%s'
-}
-
-# -- 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',
-}
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title,
-# author, documentclass [howto, manual, or own class]).
-latex_documents = [
- (master_doc, 'TF-M.tex', title,
- 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/contributing/dco.rst b/docs/contributing/dco.rst
index 7a5a4c3..b838347 100644
--- a/docs/contributing/dco.rst
+++ b/docs/contributing/dco.rst
@@ -3,7 +3,7 @@
Developer Certificate of Origin
###############################
-.. include:: /dco.txt
+.. include:: ../../dco.txt
:literal:
diff --git a/docs/contributing/lic.rst b/docs/contributing/lic.rst
index b8d4ce5..2beec63 100644
--- a/docs/contributing/lic.rst
+++ b/docs/contributing/lic.rst
@@ -3,7 +3,7 @@
License
#######
-.. include:: /license.rst
+.. include:: ../../license.rst
-----------
diff --git a/docs/technical_references/index.rst b/docs/technical_references/index.rst
index eabc0e1..200d469 100644
--- a/docs/technical_references/index.rst
+++ b/docs/technical_references/index.rst
@@ -7,7 +7,6 @@
:glob:
*/index
- /tools/index
--------------
diff --git a/docs/tfm_env.py.in b/docs/tfm_env.py.in
deleted file mode 100644
index ca5a927..0000000
--- a/docs/tfm_env.py.in
+++ /dev/null
@@ -1,24 +0,0 @@
-# -----------------------------------------------------------------------------
-# Copyright (c) 2020, Arm Limited. All rights reserved.
-#
-# SPDX-License-Identifier: BSD-3-Clause
-#
-# -----------------------------------------------------------------------------
-
-# 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" : "@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" : "@TFM_VERSION_FULL@",
- }
diff --git a/tools/documentation/tfm_cmake_defaults.py b/tools/documentation/tfm_cmake_defaults.py
deleted file mode 100644
index 1820b6a..0000000
--- a/tools/documentation/tfm_cmake_defaults.py
+++ /dev/null
@@ -1,212 +0,0 @@
-# -----------------------------------------------------------------------------
-# Copyright (c) 2020-2021, Arm Limited. All rights reserved.
-#
-# SPDX-License-Identifier: BSD-3-Clause
-#
-# -----------------------------------------------------------------------------
-
-# This module is providing the default parameters for manual Documentation
-# building. ( Without relying on CMake to determine the enviroment )
-#
-# It will however be able to communicate parameters when populated
-# by CMake (using the tfm_env.py file), and use a best-effort approach
-# to determine them when the interface file is not preset.
-
-import os
-import re
-import json
-from subprocess import check_output
-from platform import system
-
-# When called after cmake an evniroment variables file will be present
-try:
- from tfm_env import cmake_env
-except Exception as E:
- print("ERROR: Configuration Exception:", E)
- cmake_env = None
-
-tfm_def_render_cmake = True
-tfm_def_copy_files = True
-tfm_def_build_doxygen = True
-
-
-def find_tfm_root(start_dir=os.path.dirname(os.path.abspath(__file__)),
- target_files=["license.rst",
- "dco.txt",
- "toolchain_GNUARM.cmake"],
- max_depth=5):
- """ Method which attempts to find the root of the project
- by traversing parent directoried and attempts to located each of the
- files included in target_files list"""
-
- tfm_root = start_dir
-
- for i in range(max_depth):
- tfm_root = os.path.dirname(tfm_root)
- if set(target_files).issubset(set(os.listdir(tfm_root))):
- return tfm_root
- return None
-
-
-def find_package(binary_name):
- """ Attempts to resolve the abolute path for a given application or return
- empty string is nothing is found"""
-
- sys_det = system()
-
- if sys_det == "Windows":
- cmd = "where"
- # Window's where requires the extension
- binary_name = binary_name + ".exe"
- elif sys_det in ["Darwin", "Linux"]:
- cmd = "which"
- try:
- return check_output([cmd, binary_name]).decode('UTF-8').strip()
- except Exception as E:
- return ""
-
-
-def render_cmake_file(config_map, in_file, out_file):
- """ Read an input file containing CMAKE variables and try to
- render them based on a configuration map. Variables not listed
- on the map will be cleared """
-
- # Read the input file
- with open(in_file, "r", encoding='utf-8') as F:
- _data = F.read()
-
- # Render all config entires included in the map
- for k, v in config_map.items():
- v = v.replace("\\", "\\\\")
- _data = re.sub(r'@%s@' % k, r'%s' % v, _data)
-
- # Set all remaining entries to blank
- _data = re.sub(r'@[A-Z\_]+@', "", _data)
-
- # Create output file
- with open(out_file, "w", encoding='utf-8') as F:
- F.write(_data)
-
-
-# Default output director for reference_manual. It should not be empty
-tfm_def_doxy_output_dir = "reference_manual"
-
-
-if cmake_env is None:
- # #################### Automatic Defaults ( Standalone )################# #
-
- # Resolve ../../
- tfm_def_root_dir = find_tfm_root()
-
- # Set the copy files directory to whatever will be passed to sphynx-build
- tfm_def_copy_dir = os.path.abspath(os.getcwd())
-
- # Documentation base path
- tfm_def_doc_root = os.path.join(tfm_def_root_dir, "docs")
- tfm_def_copy_doc_root = os.path.join(tfm_def_copy_dir, "docs")
-
- tfm_def_doxy_root = os.path.join(tfm_def_doc_root, "doxygen")
-
- tfm_def_doxy_output_dir = os.path.join(tfm_def_copy_dir,
- tfm_def_doxy_output_dir)
-
- # Input files ( Files containing CMAKE variables )
- tfm_def_conf_in_file = os.path.join(tfm_def_doc_root, "conf.py.in")
- tfm_def_doxygen_in_file = os.path.join(tfm_def_doxy_root, "Doxyfile.in")
-
- # Attempt to detect plantUML
- _ubuntu_plantum_loc = "/usr/share/plantuml/plantuml.jar"
- if "PLANTUML_JAR_PATH" in os.environ.keys():
- tfm_def_plantum_loc = os.environ["PLANTUML_JAR_PATH"]
- elif os.path.isfile(_ubuntu_plantum_loc):
- tfm_def_plantum_loc = _ubuntu_plantum_loc
- else:
- tfm_def_plantum_loc = ""
-
- # Attempt to detect the java interpreter location
- tfm_def_java_binary = find_package("java")
- tfm_def_doxygen_loc = find_package("doxygen")
- tfm_def_doxygen_dot_loc = find_package("dot")
-
- try:
- vrex = re.compile(r'TF-M(?P<GIT_VERSION>v.+?)'
- r'(-[0-9]+-g)?(?P<GIT_SHA>[a-f0-9]{7,})?$')
-
- tfm_def_tfm_version = check_output("git describe --tags --always",
- shell = True, encoding = 'UTF-8')
-
- _v = vrex.match(tfm_def_tfm_version)
-
- tfm_def_tfm_version = _v.group("GIT_VERSION")
- if _v.group("GIT_SHA"):
- tfm_def_tfm_version += "+" + _v.group("GIT_SHA")[:7]
-
- except Exception as E:
- try:
- tfm_def_tfm_version
- except NameError:
- tfm_def_tfm_version = "Unknown"
-
-else:
- # #################### Cmake Defaults ################################## #
- tfm_def_root_dir = os.path.abspath(cmake_env["TFM_ROOT_DIR"])
- tfm_def_copy_dir = os.path.abspath(cmake_env["SPHINX_TMP_DOC_DIR"])
- tfm_def_plantum_loc = os.path.abspath(cmake_env["PLANTUML_JAR_PATH"])
- tfm_def_java_binary = os.path.abspath(cmake_env["Java_JAVA_EXECUTABLE"])
- tfm_def_tfm_version = cmake_env["SPHINXCFG_TFM_VERSION"]
- tfm_def_conf_in_file = cmake_env["SPHINXCFG_TEMPLATE_FILE"]
-
- tfm_def_copy_files = True if cmake_env["SPHINXCFG_COPY_FILES"] == "True" \
- else False
- tfm_def_render_cmake = True \
- if cmake_env["SPHINXCFG_RENDER_CONF"] == "True" else False
-
- tfm_def_build_doxygen = True \
- if cmake_env["DOXYCFG_DOXYGEN_BUILD"] == "True" else False
-
- if tfm_def_build_doxygen:
- tfm_def_doxy_root = cmake_env["DOXYCFG_DOXYGEN_CFG_DIR"]
- tfm_def_doxygen_in_file = os.path.join(tfm_def_doxy_root,
- "Doxyfile.in")
-
- # Documentation base path
- tfm_def_doc_root = os.path.join(tfm_def_root_dir, "docs")
- tfm_def_copy_doc_root = tfm_def_copy_dir
-
- # Disable copyfiles for next invocation
- cmake_env["SPHINXCFG_COPY_FILES"] = "False"
- with open("tfm_env.py", "w", encoding='utf-8') as F:
- F.write("cmake_env =" + json.dumps(cmake_env))
-
-# #################### User Defaults ######################################## #
-
-# Directories, referenced by TF-M root, which may contain releval documents
-# which need to be broughtt over
-document_scan_dirs = ["tools", "platform"]
-
-document_scan_ext = [".rst", ".md", ".jpg", ".png"]
-
-# Other documents that should be added to the root documentation folder
-documents_extra = ["license.rst", "dco.txt"]
-
-# Output files ( After CMAKE variables have been evaluated )
-tfm_def_conf_out_file = os.path.join(tfm_def_copy_dir, "conf_rendered.py")
-if tfm_def_build_doxygen:
- tfm_def_doxygen_out_file = os.path.join(tfm_def_doxy_root,
- "DoxyfileCfg.in")
-
-# If env is none, the script is running as standalone. Generate it with the
-# auto-detected values set above
-if cmake_env is None:
- cmake_env = {"TFM_ROOT_DIR": tfm_def_root_dir,
- "DOXYGEN_EXECUTABLE": tfm_def_doxygen_loc,
- "DOXYGEN_DOT_EXECUTABLE": tfm_def_doxygen_dot_loc,
- "PLANTUML_JAR_PATH": tfm_def_plantum_loc,
- "SPHINXCFG_TFM_VERSION": tfm_def_tfm_version,
- "Java_JAVA_EXECUTABLE": tfm_def_java_binary,
- "DOXYCFG_OUTPUT_PATH": tfm_def_doxy_output_dir,
- "DOXYCFG_TFM_VERSION": tfm_def_tfm_version,
- }
-# Only Override the version
-else:
- cmake_env["SPHINXCFG_TFM_VERSION"] = tfm_def_tfm_version
diff --git a/tools/documentation/tfm_copy_files.py b/tools/documentation/tfm_copy_files.py
deleted file mode 100644
index b1eb9b0..0000000
--- a/tools/documentation/tfm_copy_files.py
+++ /dev/null
@@ -1,93 +0,0 @@
-# -----------------------------------------------------------------------------
-# Copyright (c) 2020, Arm Limited. All rights reserved.
-#
-# SPDX-License-Identifier: BSD-3-Clause
-#
-# -----------------------------------------------------------------------------
-
-# Interface module for pre-processing the documentation content
-# before sphynx-build is called
-#
-# It collects files from multiple sources in a intermediate location
-# before calling sphinx-build, thus overriding the limitation
-# of having the documentation share a common root directory.
-#
-# It can be triggered by simply importing the module
-import os
-from shutil import copy2, copytree, rmtree, move
-from glob import glob
-from tfm_cmake_defaults import *
-from subprocess import call
-
-def copytree_overwrite(src, dest):
- if os.path.isdir(src):
- if not os.path.isdir(dest):
- os.makedirs(dest)
- files = os.listdir(src)
- for f in files:
- copytree_overwrite(os.path.join(src, f),
- os.path.join(dest, f))
- else:
- copy2(src, dest)
-
-def tfm_copy_files():
- doc_files = []
-
- # Recursively list all files with extensions and add them
- for _path in document_scan_dirs:
- _path = os.path.abspath(os.path.join(tfm_def_root_dir, _path))
- for ext in document_scan_ext:
- doc_files.extend([f for f in glob(os.path.join(_path,
- "**/*%s" % ext),
- recursive=True)])
-
- # Add the extra files
- for _doc_file in documents_extra:
- _doc_file = os.path.abspath(os.path.join(tfm_def_root_dir, _doc_file))
- if os.path.isfile(_doc_file):
- doc_files.append(_doc_file)
-
- # Clean up all files in target dir except conf.py and tfm_env.py
- files = [f for f in
- glob("*", recursive=False) if f not in ["conf.py",
- tfm_def_conf_out_file,
- os.path.basename(
- tfm_def_doxy_output_dir),
- "tfm_env.py"]]
- for f in files:
- if os.path.isfile(f):
- os.remove(f)
- elif os.path.isdir(f):
- rmtree(f)
-
- # Copy the documentation folder as is
- copytree_overwrite(tfm_def_doc_root, tfm_def_copy_doc_root)
-
- for df in list(doc_files):
- # Set the target filename to be cwd + relative to root path of origin
- target_f = os.path.relpath(df, tfm_def_root_dir)
- target_f = os.path.join(tfm_def_copy_dir, target_f)
- # Create path for file (nested) without exception if exists
- os.makedirs(os.path.dirname(target_f), exist_ok=True)
- # Copy the file to new location
- copy2(df, target_f)
-
-
-# Build Doxygen Documnetation
-if tfm_def_build_doxygen:
- # if conf file is not provided by cmake
- if tfm_def_render_cmake:
- render_cmake_file(cmake_env,
- tfm_def_doxygen_in_file,
- tfm_def_doxygen_out_file)
- # Call doxygen to generate the documentation
- doxygen_bin = find_package("doxygen")
- call([doxygen_bin, tfm_def_doxygen_out_file])
-
-# Only act if requested by defaults
-if tfm_def_copy_files:
- tfm_copy_files()
-
-if tfm_def_render_cmake:
- # Render the conf_py file
- render_cmake_file(cmake_env, tfm_def_conf_in_file, tfm_def_conf_out_file)
diff --git a/tools/index.rst b/tools/index.rst
deleted file mode 100644
index 9164b65..0000000
--- a/tools/index.rst
+++ /dev/null
@@ -1,10 +0,0 @@
-Tools
-=====
-
-.. toctree::
- :maxdepth: 1
- :glob:
-
---------------
-
-*Copyright (c) 2020-2022, Arm Limited. All rights reserved.*