fix(docs): fix build errors for latexpdf
Fixes errors encountered when handling SVG graphics, unicode characters,
and deeply nested lists (i.e. in the change log) with the `latexpdf`
docs build. Adds `sphinxcontrib-svg2pdfconverter` to allow embedding SVG
images into PDF files; changes the LaTeX engine to XeLaTex to provide
wider support for unicode characters (see [1] for more details); and
increases the maximum list depth.
[1] https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-latex_engine
Change-Id: I2ee265d301f6822bae7aa6dfa3a8bfcf070076d3
Signed-off-by: Harrison Mutai <harrison.mutai@arm.com>
diff --git a/.versionrc.js b/.versionrc.js
index 4e9c71f..3a21ded 100644
--- a/.versionrc.js
+++ b/.versionrc.js
@@ -101,6 +101,25 @@
"type": "json"
},
{
+ "filename": "docs/conf.py",
+ "updater": {
+ "readVersion": function (contents) {
+ const _ver = contents.match(/version\s=.*"(\d)\.(\d)\.(\d)/);
+
+ return `${_ver[1]}.${_ver[2]}.${_ver[2]}`;
+ },
+
+ "writeVersion": function (contents, version) {
+ const _ver = 'version = "' + version + '"'
+ const _rel = 'release = "' + version + '"'
+
+ contents = contents.replace(/^(version\s=\s")((\d).?)*$/m, _ver)
+ contents = contents.replace(/^(release\s=\s")((\d).?)*$/m, _rel)
+ return contents
+ }
+ },
+ },
+ {
"filename": "tools/conventional-changelog-tf-a/package.json",
"type": "json"
},
diff --git a/docs/conf.py b/docs/conf.py
index 4e8ac49..345f53b 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -9,18 +9,25 @@
#
# See the options documentation at http://www.sphinx-doc.org/en/master/config
-import os
# -- Project information -----------------------------------------------------
project = "Trusted Firmware-A"
+author = "Trusted Firmware-A contributors"
+version = "2.9.0"
+release = "2.9.0"
# -- General configuration ---------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
-extensions = ["myst_parser", "sphinx.ext.autosectionlabel", "sphinxcontrib.plantuml"]
+extensions = [
+ "myst_parser",
+ "sphinx.ext.autosectionlabel",
+ "sphinxcontrib.plantuml",
+ "sphinxcontrib.inkscapeconverter",
+]
# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]
@@ -48,7 +55,8 @@
pygments_style = "sphinx"
# Load the contents of the global substitutions file into the 'rst_prolog'
-# variable. This ensures that the substitutions are all inserted into each page.
+# variable. This ensures that the substitutions are all inserted into each
+# page.
with open("global_substitutions.txt", "r") as subs:
rst_prolog = subs.read()
@@ -93,3 +101,11 @@
# -- Options for plantuml ----------------------------------------------------
plantuml_output_format = "svg_img"
+
+# -- Options for latexmk ----------------------------------------------------
+
+latex_engine = "xelatex"
+latex_elements = {
+ "maxlistdepth": "10",
+ "pointsize": "11pt",
+}
diff --git a/poetry.lock b/poetry.lock
index 92b38da..07cd572 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -1,10 +1,9 @@
-# This file is automatically @generated by Poetry and should not be changed by hand.
+# This file is automatically @generated by Poetry 1.5.0 and should not be changed by hand.
[[package]]
name = "alabaster"
version = "0.7.13"
description = "A configurable sidebar-enabled Sphinx theme"
-category = "dev"
optional = false
python-versions = ">=3.6"
files = [
@@ -16,7 +15,6 @@
name = "anytree"
version = "2.8.0"
description = "Powerful and Lightweight Python Tree Data Structure.."
-category = "dev"
optional = false
python-versions = "*"
files = [
@@ -35,7 +33,6 @@
name = "babel"
version = "2.12.1"
description = "Internationalization utilities"
-category = "dev"
optional = false
python-versions = ">=3.7"
files = [
@@ -50,7 +47,6 @@
name = "build"
version = "0.10.0"
description = "A simple, correct Python build frontend"
-category = "dev"
optional = false
python-versions = ">= 3.7"
files = [
@@ -74,7 +70,6 @@
name = "certifi"
version = "2022.12.7"
description = "Python package for providing Mozilla's CA Bundle."
-category = "dev"
optional = false
python-versions = ">=3.6"
files = [
@@ -86,7 +81,6 @@
name = "charset-normalizer"
version = "3.1.0"
description = "The Real First Universal Charset Detector. Open, modern and actively maintained alternative to Chardet."
-category = "dev"
optional = false
python-versions = ">=3.7.0"
files = [
@@ -171,7 +165,6 @@
name = "click"
version = "8.1.3"
description = "Composable command line interface toolkit"
-category = "dev"
optional = false
python-versions = ">=3.7"
files = [
@@ -186,7 +179,6 @@
name = "colorama"
version = "0.4.6"
description = "Cross-platform colored terminal text."
-category = "dev"
optional = false
python-versions = "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,!=3.6.*,>=2.7"
files = [
@@ -198,7 +190,6 @@
name = "docutils"
version = "0.18.1"
description = "Docutils -- Python Documentation Utilities"
-category = "dev"
optional = false
python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*"
files = [
@@ -210,7 +201,6 @@
name = "idna"
version = "3.4"
description = "Internationalized Domain Names in Applications (IDNA)"
-category = "dev"
optional = false
python-versions = ">=3.5"
files = [
@@ -222,7 +212,6 @@
name = "imagesize"
version = "1.4.1"
description = "Getting image size from png/jpeg/jpeg2000/gif file"
-category = "dev"
optional = false
python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*"
files = [
@@ -234,7 +223,6 @@
name = "importlib-metadata"
version = "6.6.0"
description = "Read metadata from Python packages"
-category = "dev"
optional = false
python-versions = ">=3.7"
files = [
@@ -254,7 +242,6 @@
name = "jinja2"
version = "3.1.2"
description = "A very fast and expressive template engine."
-category = "dev"
optional = false
python-versions = ">=3.7"
files = [
@@ -272,7 +259,6 @@
name = "markdown-it-py"
version = "2.2.0"
description = "Python port of markdown-it. Markdown parsing, done right!"
-category = "dev"
optional = false
python-versions = ">=3.7"
files = [
@@ -297,7 +283,6 @@
name = "markupsafe"
version = "2.1.2"
description = "Safely add untrusted strings to HTML/XML markup."
-category = "dev"
optional = false
python-versions = ">=3.7"
files = [
@@ -357,7 +342,6 @@
name = "mdit-py-plugins"
version = "0.3.5"
description = "Collection of plugins for markdown-it-py"
-category = "dev"
optional = false
python-versions = ">=3.7"
files = [
@@ -377,7 +361,6 @@
name = "mdurl"
version = "0.1.2"
description = "Markdown URL utilities"
-category = "dev"
optional = false
python-versions = ">=3.7"
files = [
@@ -389,7 +372,6 @@
name = "myst-parser"
version = "0.18.1"
description = "An extended commonmark compliant parser, with bridges to docutils & sphinx."
-category = "dev"
optional = false
python-versions = ">=3.7"
files = [
@@ -416,7 +398,6 @@
name = "packaging"
version = "23.1"
description = "Core utilities for Python packages"
-category = "dev"
optional = false
python-versions = ">=3.7"
files = [
@@ -428,7 +409,6 @@
name = "pip"
version = "23.1.2"
description = "The PyPA recommended tool for installing Python packages."
-category = "dev"
optional = false
python-versions = ">=3.7"
files = [
@@ -440,7 +420,6 @@
name = "pip-tools"
version = "6.13.0"
description = "pip-tools keeps your pinned dependencies fresh."
-category = "dev"
optional = false
python-versions = ">=3.7"
files = [
@@ -463,7 +442,6 @@
name = "prettytable"
version = "3.7.0"
description = "A simple Python library for easily displaying tabular data in a visually appealing ASCII table format"
-category = "dev"
optional = false
python-versions = ">=3.7"
files = [
@@ -481,7 +459,6 @@
name = "pyelftools"
version = "0.29"
description = "Library for analyzing ELF files and DWARF debugging information"
-category = "dev"
optional = false
python-versions = "*"
files = [
@@ -493,7 +470,6 @@
name = "pygments"
version = "2.15.1"
description = "Pygments is a syntax highlighting package written in Python."
-category = "dev"
optional = false
python-versions = ">=3.7"
files = [
@@ -508,7 +484,6 @@
name = "pyproject-hooks"
version = "1.0.0"
description = "Wrappers to call pyproject.toml-based build backend hooks."
-category = "dev"
optional = false
python-versions = ">=3.7"
files = [
@@ -523,7 +498,6 @@
name = "pytz"
version = "2023.3"
description = "World timezone definitions, modern and historical"
-category = "dev"
optional = false
python-versions = "*"
files = [
@@ -535,7 +509,6 @@
name = "pyyaml"
version = "6.0"
description = "YAML parser and emitter for Python"
-category = "dev"
optional = false
python-versions = ">=3.6"
files = [
@@ -585,7 +558,6 @@
name = "requests"
version = "2.30.0"
description = "Python HTTP for Humans."
-category = "dev"
optional = false
python-versions = ">=3.7"
files = [
@@ -607,7 +579,6 @@
name = "setuptools"
version = "67.7.2"
description = "Easily download, build, install, upgrade, and uninstall Python packages"
-category = "dev"
optional = false
python-versions = ">=3.7"
files = [
@@ -624,7 +595,6 @@
name = "six"
version = "1.16.0"
description = "Python 2 and 3 compatibility utilities"
-category = "dev"
optional = false
python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*"
files = [
@@ -636,7 +606,6 @@
name = "snowballstemmer"
version = "2.2.0"
description = "This package provides 29 stemmers for 28 languages generated from Snowball algorithms."
-category = "dev"
optional = false
python-versions = "*"
files = [
@@ -648,7 +617,6 @@
name = "sphinx"
version = "5.3.0"
description = "Python documentation generator"
-category = "dev"
optional = false
python-versions = ">=3.6"
files = [
@@ -684,7 +652,6 @@
name = "sphinx-rtd-theme"
version = "1.2.0"
description = "Read the Docs theme for Sphinx"
-category = "dev"
optional = false
python-versions = "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,>=2.7"
files = [
@@ -704,7 +671,6 @@
name = "sphinxcontrib-applehelp"
version = "1.0.4"
description = "sphinxcontrib-applehelp is a Sphinx extension which outputs Apple help books"
-category = "dev"
optional = false
python-versions = ">=3.8"
files = [
@@ -720,7 +686,6 @@
name = "sphinxcontrib-devhelp"
version = "1.0.2"
description = "sphinxcontrib-devhelp is a sphinx extension which outputs Devhelp document."
-category = "dev"
optional = false
python-versions = ">=3.5"
files = [
@@ -736,7 +701,6 @@
name = "sphinxcontrib-htmlhelp"
version = "2.0.1"
description = "sphinxcontrib-htmlhelp is a sphinx extension which renders HTML help files"
-category = "dev"
optional = false
python-versions = ">=3.8"
files = [
@@ -752,7 +716,6 @@
name = "sphinxcontrib-jquery"
version = "4.1"
description = "Extension to include jQuery on newer Sphinx releases"
-category = "dev"
optional = false
python-versions = ">=2.7"
files = [
@@ -767,7 +730,6 @@
name = "sphinxcontrib-jsmath"
version = "1.0.1"
description = "A sphinx extension which renders display math in HTML via JavaScript"
-category = "dev"
optional = false
python-versions = ">=3.5"
files = [
@@ -782,7 +744,6 @@
name = "sphinxcontrib-plantuml"
version = "0.24.1"
description = "Sphinx \"plantuml\" extension"
-category = "dev"
optional = false
python-versions = "*"
files = [
@@ -799,7 +760,6 @@
name = "sphinxcontrib-qthelp"
version = "1.0.3"
description = "sphinxcontrib-qthelp is a sphinx extension which outputs QtHelp document."
-category = "dev"
optional = false
python-versions = ">=3.5"
files = [
@@ -815,7 +775,6 @@
name = "sphinxcontrib-serializinghtml"
version = "1.1.5"
description = "sphinxcontrib-serializinghtml is a sphinx extension which outputs \"serialized\" HTML files (json and pickle)."
-category = "dev"
optional = false
python-versions = ">=3.5"
files = [
@@ -828,10 +787,26 @@
test = ["pytest"]
[[package]]
+name = "sphinxcontrib-svg2pdfconverter"
+version = "1.2.2"
+description = "Sphinx SVG to PDF converter extension"
+optional = false
+python-versions = "~=3.4"
+files = [
+ {file = "sphinxcontrib-svg2pdfconverter-1.2.2.tar.gz", hash = "sha256:80a55ca61f70eae93efc65f3814f2f177c86ba55934a9f6c5022f1778b62146b"},
+ {file = "sphinxcontrib_svg2pdfconverter-1.2.2-py3-none-any.whl", hash = "sha256:04ec767b55780a6b18d89cc1a8ada6d900c6efde9d1683abdb98a49b144465ca"},
+]
+
+[package.dependencies]
+Sphinx = ">=1.6.3"
+
+[package.extras]
+cairosvg = ["cairosvg (>=1.0)"]
+
+[[package]]
name = "tomli"
version = "2.0.1"
description = "A lil' TOML parser"
-category = "dev"
optional = false
python-versions = ">=3.7"
files = [
@@ -843,7 +818,6 @@
name = "typing-extensions"
version = "4.5.0"
description = "Backported and Experimental Type Hints for Python 3.7+"
-category = "dev"
optional = false
python-versions = ">=3.7"
files = [
@@ -855,7 +829,6 @@
name = "urllib3"
version = "2.0.2"
description = "HTTP library with thread-safe connection pooling, file post, and more."
-category = "dev"
optional = false
python-versions = ">=3.7"
files = [
@@ -873,7 +846,6 @@
name = "wcwidth"
version = "0.2.6"
description = "Measures the displayed width of unicode strings in a terminal"
-category = "dev"
optional = false
python-versions = "*"
files = [
@@ -885,7 +857,6 @@
name = "wheel"
version = "0.40.0"
description = "A built-package format for Python"
-category = "dev"
optional = false
python-versions = ">=3.7"
files = [
@@ -900,7 +871,6 @@
name = "zipp"
version = "3.15.0"
description = "Backport of pathlib-compatible object wrapper for zip files"
-category = "dev"
optional = false
python-versions = ">=3.7"
files = [
@@ -915,4 +885,4 @@
[metadata]
lock-version = "2.0"
python-versions = "^3.8"
-content-hash = "9c25ef33612d10c7caafa551a3cf6a12753167c6400f49cc261fddd18c7eaf6e"
+content-hash = "62d9ce9ca1c9f4669c7b40724acfc93968cde31c0460d1d7515d289739dc9464"
diff --git a/pyproject.toml b/pyproject.toml
index 44e78d3..19ba4d8 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -21,6 +21,7 @@
sphinxcontrib-plantuml = "^0.24.1"
sphinx-rtd-theme = "^1.1.1"
pip-tools = "^6.4.0"
+sphinxcontrib-svg2pdfconverter = "^1.2.2"
[tool.poetry.group.ci.dependencies]
click = "^8.1.3"