Skip to content

Commit b813dbc

Browse files
Anton-TFAnton-TF
committed
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 <[email protected]> Change-Id: I0c49043cda43dca263f530dde13052bcf9f49046
1 parent e25c1b4 commit b813dbc

File tree

10 files changed

+203
-592
lines changed

10 files changed

+203
-592
lines changed

‎docs/CMakeLists.txt

+9-28
Original file line numberDiff line numberDiff line change
@@ -27,46 +27,28 @@ include(../cmake/version.cmake)
2727

2828
project("Trusted Firmware M. Documentation" VERSION ${TFM_VERSION} LANGUAGES)
2929

30+
set(SPHINXCFG_SOURCE_PATH ${CMAKE_CURRENT_SOURCE_DIR})
31+
set(SPHINXCFG_CONFIG_PATH ${CMAKE_CURRENT_SOURCE_DIR})
3032
set(SPHINXCFG_OUTPUT_PATH ${CMAKE_CURRENT_BINARY_DIR}/user_guide)
31-
set(SPHINX_TMP_DOC_DIR ${CMAKE_CURRENT_BINARY_DIR}/temp)
32-
set(SPHINXCFG_TEMPLATE_FILE "${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in")
33+
3334
set(DOXYCFG_OUTPUT_PATH ${CMAKE_CURRENT_BINARY_DIR}/reference_manual)
3435
set(DOXYCFG_DOXYGEN_CFG_DIR ${CMAKE_SOURCE_DIR}/doxygen)
3536

3637
# Enable to request the interface to build the doxygen documentation as well
3738
set(DOXYCFG_DOXYGEN_BUILD False)
3839

3940
################################## SPHINX ######################################
40-
set(SPHINXCFG_COPY_FILES True)
41-
set(SPHINXCFG_RENDER_CONF True)
42-
43-
add_custom_target(tfm_docs_sphinx_cfg
44-
DEPENDS ${SPHINX_TMP_DOC_DIR}/conf.py
45-
)
46-
add_custom_command(OUTPUT ${SPHINX_TMP_DOC_DIR}/conf.py
47-
COMMAND ${CMAKE_COMMAND} -E make_directory ${SPHINX_TMP_DOC_DIR}
48-
COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_SOURCE_DIR}/conf.py ${SPHINX_TMP_DOC_DIR}/conf.py
49-
MAIN_DEPENDENCY ${CMAKE_SOURCE_DIR}/conf.py
50-
BYPRODUCTS ${SPHINX_TMP_DOC_DIR}
51-
)
52-
53-
configure_file(${CMAKE_CURRENT_SOURCE_DIR}/tfm_env.py.in ${SPHINX_TMP_DOC_DIR}/tfm_env.py @ONLY)
5441

5542
if (SPHINX_FOUND AND PLANTUML_FOUND AND PY_M2R2_FOUND AND PY_SPHINX-RTD-THEME_FOUND AND PY_SPHINXCONTRIB.PLANTUML)
5643

57-
file(GLOB_RECURSE SPHINXCFG_DOC_FILES ${CMAKE_CURRENT_SOURCE_DIR}/*.rst)
44+
file(GLOB_RECURSE SPHINXCFG_DOC_FILES ${SPHINXCFG_SOURCE_PATH}/*.rst)
5845

59-
add_custom_command(OUTPUT "${SPHINXCFG_OUTPUT_PATH}/html/index.html"
60-
OUTPUT "${SPHINXCFG_OUTPUT_PATH}/html/"
61-
COMMAND "${SPHINX_EXECUTABLE}" -W -b html "${SPHINX_TMP_DOC_DIR}" "${SPHINXCFG_OUTPUT_PATH}/html"
62-
WORKING_DIRECTORY "${CMAKE_SOURCE_DIR}"
63-
DEPENDS tfm_docs_sphinx_cfg
64-
DEPENDS ${SPHINXCFG_DOC_FILES}
65-
)
6646
add_custom_target(tfm_docs_userguide_html ALL
67-
DEPENDS "${SPHINXCFG_OUTPUT_PATH}/html/index.html"
68-
DEPENDS "${SPHINXCFG_OUTPUT_PATH}/html/"
47+
COMMAND "${SPHINX_EXECUTABLE}" -W -b html -j auto -c ${SPHINXCFG_CONFIG_PATH} ${SPHINXCFG_SOURCE_PATH} "${SPHINXCFG_OUTPUT_PATH}/html"
48+
WORKING_DIRECTORY ${SPHINXCFG_SOURCE_PATH}
49+
DEPENDS ${SPHINXCFG_DOC_FILES}
6950
)
51+
7052
add_dependencies(docs tfm_docs_userguide_html)
7153

7254
if (LATEX_PDFLATEX_FOUND)
@@ -92,10 +74,9 @@ endif()
9274

9375
################################## DOXYGEN #####################################
9476

95-
configure_file(${CMAKE_SOURCE_DIR}/doxygen/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY)
96-
9777
if (DOXYGEN_FOUND AND DOXYGEN_DOT_FOUND AND PLANTUML_FOUND)
9878

79+
configure_file(${CMAKE_SOURCE_DIR}/doxygen/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY)
9980
file(GLOB_RECURSE DOXYCFG_DOC_FILES ${CMAKE_SOURCE_DIR}/*.c ${CMAKE_SOURCE_DIR}/*.h)
10081

10182
add_custom_command(OUTPUT ${DOXYCFG_OUTPUT_PATH}/html

‎docs/conf.py

+192-21
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,203 @@
1-
# -----------------------------------------------------------------------------
2-
# Copyright (c) 2020, Arm Limited. All rights reserved.
1+
# -*- coding: utf-8 -*-
2+
#-------------------------------------------------------------------------------
3+
# Copyright (c) 2019-2022, Arm Limited. All rights reserved.
34
#
45
# SPDX-License-Identifier: BSD-3-Clause
56
#
6-
# -----------------------------------------------------------------------------
7-
#
8-
# Configuration file override for the Sphinx documentation builder.
7+
#-------------------------------------------------------------------------------
8+
9+
# Configuration file for the Sphinx documentation builder.
910
#
10-
# This file is used when Sphinx build is invoked directly at this level.
11-
# It will trigger a copy-files operation and render a new configuration
12-
# using either auto-detected or cmake provided parameters.
11+
# This file does only contain a selection of the most common options. For a
12+
# full list see the documentation:
13+
# http://www.sphinx-doc.org/en/master/config
14+
1315
import os
1416
import sys
17+
import re
18+
from subprocess import check_output
19+
20+
# -- Project information -----------------------------------------------------
21+
22+
project = 'Trusted Firmware-M'
23+
copyright = '2017-2022, ARM CE-OSS'
24+
author = 'ARM CE-OSS'
25+
title = 'User Guide'
26+
27+
# -- Extract current version -------------------------------------------------
28+
29+
try:
30+
vrex = re.compile(r'TF-M(?P<GIT_VERSION>v.+?)'
31+
r'(-[0-9]+-g)?(?P<GIT_SHA>[a-f0-9]{7,})?$')
32+
33+
version = check_output("git describe --tags --always",
34+
shell = True, encoding = 'UTF-8')
35+
36+
_v = vrex.match(version)
37+
release = _v.group('GIT_VERSION')
38+
if _v.group('GIT_SHA'):
39+
version = release + "+" + _v.group('GIT_SHA')[:7]
40+
41+
except:
42+
version = release = 'Unknown'
43+
44+
# -- General configuration ---------------------------------------------------
45+
46+
# If your documentation needs a minimal Sphinx version, state it here.
47+
#
48+
# needs_sphinx = '1.4'
49+
50+
# Add any Sphinx extension module names here, as strings. They can be
51+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
52+
# ones.
53+
extensions = [
54+
'sphinx.ext.imgmath',
55+
'm2r2', #Support markdown files. Needed for external code.
56+
'sphinx.ext.autosectionlabel', #Make sphinx generate a label for each section
57+
'sphinxcontrib.plantuml', #Add support for PlantUML drawings
58+
'sphinxcontrib.rsvgconverter', #Add support for SVG to PDF
59+
'sphinx_tabs.tabs' #Enable tab extension in Sphinx
60+
]
61+
62+
# PlantUML
63+
plantuml = 'java -jar ' + os.environ['PLANTUML_JAR_PATH']
64+
65+
#Make auso section labals generated be prefixed with file name.
66+
autosectionlabel_prefix_document=True
67+
#Add auso section label for level 2 headers only.
68+
autosectionlabel_maxdepth=2
69+
70+
# Add any paths that contain templates here, relative to this directory.
71+
templates_path = ['_templates']
72+
73+
# The suffix(es) of source filenames.
74+
# You can specify multiple suffix as a list of string:
75+
#
76+
source_suffix = ['.rst', '.md']
77+
78+
# The master toctree document.
79+
master_doc = 'index'
80+
81+
# The language for content autogenerated by Sphinx. Refer to documentation
82+
# for a list of supported languages.
83+
#
84+
# This is also used if you do content translation via gettext catalogs.
85+
# Usually you set "language" from the command line for these cases.
86+
language = None
87+
88+
# List of patterns, relative to source directory, that match files and
89+
# directories to ignore when looking for source files.
90+
# This pattern also affects html_static_path and html_extra_path .
91+
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'readme.rst',
92+
'platform/ext/target/cypress/psoc64/security/keys/readme.rst',
93+
'lib/ext/**']
94+
95+
# The name of the Pygments (syntax highlighting) style to use.
96+
pygments_style = 'sphinx'
97+
98+
# -- Options for HTML output -------------------------------------------------
99+
100+
# The theme to use for HTML and HTML Help pages. See the documentation for
101+
# a list of builtin themes.
102+
#
103+
html_theme = 'sphinx_rtd_theme'
104+
105+
# Theme options are theme-specific and customize the look and feel of a theme
106+
# further. For a list of options available for each theme, see the
107+
# documentation.
108+
#
109+
html_theme_options = {'collapse_navigation': False}
110+
#
111+
# Add any paths that contain custom static files (such as style sheets) here,
112+
# relative to configuration directory. They are copied after the builtin static
113+
# files, so a file named "default.css" will overwrite the builtin "default.css".
114+
html_static_path = ['_static']
115+
116+
# Set the documentation logo relative to configuration directory
117+
html_logo = '_static/images/tf_logo_white.png'
118+
119+
# Custom sidebar templates, must be a dictionary that maps document names
120+
# to template names.
121+
#
122+
# The default sidebars (for documents that don't match any pattern) are
123+
# defined by theme itself. Builtin themes are using these templates by
124+
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
125+
# 'searchbox.html']``.
126+
#
127+
# html_sidebars = {}
128+
129+
#Disable adding conf.py copyright notice to HTML output
130+
html_show_copyright = False
131+
132+
#Add custom css for HTML. Used to allow full page width rendering
133+
def setup(app):
134+
app.add_css_file('css/tfm_custom.css')
135+
136+
# -- Options for HTMLHelp output ---------------------------------------------
137+
138+
# Output file base name for HTML help builder.
139+
htmlhelp_basename = 'TF-M doc'
140+
141+
rst_prolog = """
142+
.. |TFM_VERSION| replace:: version
143+
"""
144+
145+
# Enable figures and tables auto numbering
146+
numfig = True
147+
numfig_secnum_depth = 0
148+
numfig_format = {
149+
'figure': 'Figure %s:',
150+
'table': 'Table %s:',
151+
'code-block': 'Listing %s:',
152+
'section': '%s'
153+
}
154+
155+
# -- Options for LaTeX output ------------------------------------------------
156+
157+
latex_elements = {
158+
# The paper size ('letterpaper' or 'a4paper').
159+
#
160+
# 'papersize': 'letterpaper',
161+
162+
# The font size ('10pt', '11pt' or '12pt').
163+
#
164+
# 'pointsize': '10pt',
165+
166+
# Additional stuff for the LaTeX preamble.
167+
#
168+
# 'preamble': '',
169+
170+
# Latex figure (float) alignment
171+
#
172+
# 'figure_align': 'htbp',
173+
}
174+
175+
# Grouping the document tree into LaTeX files. List of tuples
176+
# (source start file, target name, title,
177+
# author, documentclass [howto, manual, or own class]).
178+
latex_documents = [
179+
(master_doc, 'TF-M.tex', title,
180+
author, 'manual'),
181+
]
15182

16-
# Attempt to find the tools directory by recursing up to five levels of parents
17-
root_path = os.path.dirname(os.path.abspath(__file__))
183+
# -- Options for manual page output ------------------------------------------
18184

19-
for i in range(5):
20-
root_path = os.path.dirname(root_path)
21-
doc_path = os.path.join(root_path, "tools", "documentation")
22-
if os.path.isdir(doc_path):
23-
sys.path.insert(0, os.path.abspath(doc_path))
24-
sys.path.append("./")
185+
# One entry per manual page. List of tuples
186+
# (source start file, name, description, authors, manual section).
187+
#man_pages = [
188+
# (master_doc, 'tf-m', title,
189+
# [author], 7)
190+
#]
25191

26-
# Trigger the copy operation logic
27-
import tfm_copy_files
192+
# -- Options for Texinfo output ----------------------------------------------
28193

29-
# Import the rendered configuration into global scope
30-
from tfm_cmake_defaults import *
194+
# Grouping the document tree into Texinfo files. List of tuples
195+
# (source start file, target name, title, author,
196+
# dir menu entry, description, category)
197+
#texinfo_documents = [
198+
# (master_doc, 'TF-M', title,
199+
# author, 'TF-M', 'Trusted Firmware for Cortex-M',
200+
# 'Miscellaneous'),
201+
#]
31202

32-
from conf_rendered import *
203+
# -- Extension configuration -------------------------------------------------

0 commit comments

Comments
 (0)