doc: pdf: add ImageMagick converter extension

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é <benjamin@zephyrproject.org>

.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

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}

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"]
 

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