From 9ee3bf221d0288f123cd193d78984cac2d95e22e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Benjamin=20Cab=C3=A9?= Date: Wed, 5 Jun 2024 18:31:56 +0200 Subject: [PATCH] doc: pdf: add ImageMagick converter extension MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Our documentation uses image formats such as WebP that are not supported by LaTeX. This commit enables Sphinx's sphinx.ext.imageconverter extension, and updates the documentation to indicate ImageMagick is required to build docs. Signed-off-by: Benjamin Cabé --- .github/workflows/doc-build.yml | 2 +- doc/CMakeLists.txt | 2 +- doc/conf.py | 8 ++++++-- doc/contribute/documentation/generation.rst | 12 ++++++------ 4 files changed, 14 insertions(+), 10 deletions(-) diff --git a/.github/workflows/doc-build.yml b/.github/workflows/doc-build.yml index d7c1edd6a65..c50625a1879 100644 --- a/.github/workflows/doc-build.yml +++ b/.github/workflows/doc-build.yml @@ -217,7 +217,7 @@ jobs: - name: install-pkgs run: | apt-get update - apt-get install -y python3-pip python3-venv ninja-build doxygen graphviz librsvg2-bin + apt-get install -y python3-pip python3-venv ninja-build doxygen graphviz librsvg2-bin imagemagick - name: cache-pip uses: actions/cache@v4 diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 5cfce578a4a..e72b7ac2298 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -174,7 +174,7 @@ add_doc_target( -d ${DOCS_DOCTREE_DIR} -w ${DOCS_BUILD_DIR}/latex.log -t ${DOC_TAG} - -t svgconvert + -t convertimages ${SPHINXOPTS} ${SPHINXOPTS_EXTRA} ${DOCS_SRC_DIR} diff --git a/doc/conf.py b/doc/conf.py index ff54dd2cc49..a86f09b0542 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -99,9 +99,13 @@ extensions = [ "zephyr.api_overview", ] -# Only use SVG converter when it is really needed, e.g. LaTeX. -if tags.has("svgconvert"): # pylint: disable=undefined-variable +# Only use image conversion when it is really needed, e.g. LaTeX build. +# Ensure "sphinxcontrib.rsvgconverter" is added before "sphinx.ext.imgconverter" +# as it's better at converting SVG with extended features (like the ones from +# draw.io) to PDF format). +if tags.has("convertimages"): # pylint: disable=undefined-variable extensions.append("sphinxcontrib.rsvgconverter") + extensions.append("sphinx.ext.imgconverter") templates_path = ["_templates"] diff --git a/doc/contribute/documentation/generation.rst b/doc/contribute/documentation/generation.rst index 3991b19c47d..f51eb59e44e 100644 --- a/doc/contribute/documentation/generation.rst +++ b/doc/contribute/documentation/generation.rst @@ -105,27 +105,27 @@ as described below: .. code-block:: console sudo apt-get install --no-install-recommends doxygen graphviz librsvg2-bin \ - texlive-latex-base texlive-latex-extra latexmk texlive-fonts-recommended + texlive-latex-base texlive-latex-extra latexmk texlive-fonts-recommended imagemagick On Fedora Linux: .. code-block:: console sudo dnf install doxygen graphviz texlive-latex latexmk \ - texlive-collection-fontsrecommended librsvg2-tools + texlive-collection-fontsrecommended librsvg2-tools ImageMagick On Clear Linux: .. code-block:: console - sudo swupd bundle-add texlive graphviz + sudo swupd bundle-add texlive graphviz ImageMagick On Arch Linux: .. code-block:: console sudo pacman -S graphviz doxygen librsvg texlive-core texlive-bin \ - texlive-latexextra texlive-fontsextra + texlive-latexextra texlive-fontsextra imagemagick .. group-tab:: macOS @@ -139,7 +139,7 @@ as described below: .. code-block:: console - brew install doxygen graphviz mactex librsvg + brew install doxygen graphviz mactex librsvg imagemagick tlmgr install latexmk tlmgr install collection-fontsrecommended @@ -155,7 +155,7 @@ as described below: .. code-block:: console - choco install doxygen.install graphviz strawberryperl miktex rsvg-convert + choco install doxygen.install graphviz strawberryperl miktex rsvg-convert imagemagick .. note:: On Windows, the Sphinx executable ``sphinx-build.exe`` is placed in