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
This commit is contained in:
Anton Komlev
Anton Komlev
parent
e25c1b46df
commit
b813dbcfef
|
|
@ -27,9 +27,10 @@ include(../cmake/version.cmake)
|
|||
|
||||
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_CFG_DIR ${CMAKE_SOURCE_DIR}/doxygen)
|
|||
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 @@ endif()
|
|||
|
||||
################################## 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
|
||||
|
|
|
|||
213
docs/conf.py
213
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 -------------------------------------------------
|
||||
|
|
|
|||
201
docs/conf.py.in
201
docs/conf.py.in
|
|
@ -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 -------------------------------------------------
|
||||
|
|
@ -3,7 +3,7 @@
|
|||
Developer Certificate of Origin
|
||||
###############################
|
||||
|
||||
.. include:: /dco.txt
|
||||
.. include:: ../../dco.txt
|
||||
:literal:
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
License
|
||||
#######
|
||||
|
||||
.. include:: /license.rst
|
||||
.. include:: ../../license.rst
|
||||
|
||||
-----------
|
||||
|
||||
|
|
|
|||
|
|
@ -7,7 +7,6 @@ Technical References
|
|||
:glob:
|
||||
|
||||
*/index
|
||||
/tools/index
|
||||
|
||||
--------------
|
||||
|
||||
|
|
|
|||
|
|
@ -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@",
|
||||
}
|
||||
|
|
@ -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
|
||||
|
|
@ -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)
|
||||
|
|
@ -1,10 +0,0 @@
|
|||
Tools
|
||||
=====
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:glob:
|
||||
|
||||
--------------
|
||||
|
||||
*Copyright (c) 2020-2022, Arm Limited. All rights reserved.*
|
||||
Loading…
Reference in New Issue