From 443d6ea69992986f56246bcee44e537ab8dec069 Mon Sep 17 00:00:00 2001 From: Harrison Mutai Date: Wed, 31 May 2023 10:18:49 +0100 Subject: [PATCH] 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 --- .versionrc.js | 19 ++++++++++++++ docs/conf.py | 22 +++++++++++++--- poetry.lock | 68 ++++++++++++++------------------------------------ pyproject.toml | 1 + 4 files changed, 58 insertions(+), 52 deletions(-) diff --git a/.versionrc.js b/.versionrc.js index 4e9c71fb5..3a21ded31 100644 --- a/.versionrc.js +++ b/.versionrc.js @@ -100,6 +100,25 @@ module.exports = { "filename": "package-lock.json", "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 4e8ac4905..345f53bea 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 @@ exclude_patterns = [".env", "env", ".venv", "venv"] 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 @@ autosectionlabel_maxdepth = 1 # -- 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 92b38da1a..07cd572a7 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 @@ files = [ 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 @@ test = ["coverage"] name = "babel" version = "2.12.1" description = "Internationalization utilities" -category = "dev" optional = false python-versions = ">=3.7" files = [ @@ -50,7 +47,6 @@ pytz = {version = ">=2015.7", markers = "python_version < \"3.9\""} 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 @@ virtualenv = ["virtualenv (>=20.0.35)"] 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 @@ files = [ 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 @@ files = [ 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 @@ colorama = {version = "*", markers = "platform_system == \"Windows\""} 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 @@ files = [ 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 @@ files = [ 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 @@ files = [ 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 @@ files = [ 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 @@ testing = ["flake8 (<5)", "flufl.flake8", "importlib-resources (>=1.3)", "packag 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 @@ i18n = ["Babel (>=2.7)"] 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 @@ testing = ["coverage", "pytest", "pytest-cov", "pytest-regressions"] 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 @@ files = [ 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 @@ testing = ["coverage", "pytest", "pytest-cov", "pytest-regressions"] name = "mdurl" version = "0.1.2" description = "Markdown URL utilities" -category = "dev" optional = false python-versions = ">=3.7" files = [ @@ -389,7 +372,6 @@ files = [ 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 @@ testing = ["beautifulsoup4", "coverage[toml]", "pytest (>=6,<7)", "pytest-cov", name = "packaging" version = "23.1" description = "Core utilities for Python packages" -category = "dev" optional = false python-versions = ">=3.7" files = [ @@ -428,7 +409,6 @@ files = [ 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 @@ files = [ 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 @@ testing = ["flit-core (>=2,<4)", "poetry-core (>=1.0.0)", "pytest (>=7.2.0)", "p 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 @@ tests = ["pytest", "pytest-cov", "pytest-lazy-fixture"] 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 @@ files = [ 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 @@ plugins = ["importlib-metadata"] 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 @@ tomli = {version = ">=1.1.0", markers = "python_version < \"3.11\""} name = "pytz" version = "2023.3" description = "World timezone definitions, modern and historical" -category = "dev" optional = false python-versions = "*" files = [ @@ -535,7 +509,6 @@ files = [ 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 @@ files = [ name = "requests" version = "2.30.0" description = "Python HTTP for Humans." -category = "dev" optional = false python-versions = ">=3.7" files = [ @@ -607,7 +579,6 @@ use-chardet-on-py3 = ["chardet (>=3.0.2,<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 @@ testing-integration = ["build[virtualenv]", "filelock (>=3.4.0)", "jaraco.envs ( 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 @@ files = [ 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 @@ files = [ name = "sphinx" version = "5.3.0" description = "Python documentation generator" -category = "dev" optional = false python-versions = ">=3.6" files = [ @@ -684,7 +652,6 @@ test = ["cython", "html5lib", "pytest (>=4.6)", "typed_ast"] 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 @@ dev = ["bump2version", "sphinxcontrib-httpdomain", "transifex-client", "wheel"] 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 @@ test = ["pytest"] 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 @@ test = ["pytest"] 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 @@ test = ["html5lib", "pytest"] 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 @@ Sphinx = ">=1.8" 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 @@ test = ["flake8", "mypy", "pytest"] name = "sphinxcontrib-plantuml" version = "0.24.1" description = "Sphinx \"plantuml\" extension" -category = "dev" optional = false python-versions = "*" files = [ @@ -799,7 +760,6 @@ test = ["Pillow", "flake8", "pytest"] 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 @@ test = ["pytest"] 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 = [ @@ -827,11 +786,27 @@ files = [ lint = ["docutils-stubs", "flake8", "mypy"] 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 @@ files = [ 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 @@ files = [ 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 @@ zstd = ["zstandard (>=0.18.0)"] 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 @@ files = [ 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 @@ test = ["pytest (>=6.0.0)"] 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 @@ testing = ["big-O", "flake8 (<5)", "jaraco.functools", "jaraco.itertools", "more [metadata] lock-version = "2.0" python-versions = "^3.8" -content-hash = "9c25ef33612d10c7caafa551a3cf6a12753167c6400f49cc261fddd18c7eaf6e" +content-hash = "62d9ce9ca1c9f4669c7b40724acfc93968cde31c0460d1d7515d289739dc9464" diff --git a/pyproject.toml b/pyproject.toml index 44e78d36a..19ba4d84d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -21,6 +21,7 @@ myst-parser = "^0.18.1" 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"