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@",
- }