docs-infra: convert webp/svg images for PDF builds (sphinx.ext.imgconverter + ImageMagick/librsvg)

🤖 Generated by [robots](https://vyos.io)

3 files changed, 84 insertions, 1 deletions

diff --git a/docker/Dockerfile b/docker/Dockerfile
index fee5c91c..8dddc8a8 100644
--- a/docker/Dockerfile
+++ b/docker/Dockerfile
@@ -25,7 +25,9 @@ RUN apt-get update && apt-get install -y \
     gosu \
     graphviz \
     curl \
-    dos2unix
+    dos2unix \
+    imagemagick \
+    librsvg2-bin
 
 RUN pip3 install --break-system-packages \
     Sphinx \
@@ -54,4 +56,12 @@ COPY entrypoint.sh /usr/local/bin/entrypoint.sh
 #     "no such file or directory"
 RUN dos2unix /usr/local/bin/entrypoint.sh
 
+# sphinx.ext.imgconverter's `image_converter` command (docs/conf.py sets
+# image_converter = 'im-convert'). Routes .svg sources to rsvg-convert
+# directly, since Debian's imagemagick package is built --without-rsvg and
+# its built-in SVG coder can't handle embedded base64 raster <image>
+# elements. See docker/im-convert.sh for the full rationale.
+COPY im-convert.sh /usr/local/bin/im-convert
+RUN dos2unix /usr/local/bin/im-convert && chmod +x /usr/local/bin/im-convert
+
 ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]
diff --git a/docker/im-convert.sh b/docker/im-convert.sh
new file mode 100644
index 00000000..e64f5f31
--- /dev/null
+++ b/docker/im-convert.sh
@@ -0,0 +1,47 @@
+#!/bin/bash
+# Wrapper invoked by sphinx.ext.imgconverter as the `image_converter` command
+# (docs/conf.py sets image_converter = 'im-convert').
+#
+# Sphinx calls it as: im-convert "<src>[0]" "<dst>" (the "[0]" frame-index
+# suffix is ImageMagick syntax for "first frame/page", appended unconditionally
+# by sphinx/ext/imgconverter.py).
+#
+# Debian's `imagemagick` package is built --without-rsvg (LGPL licensing), so
+# its own SVG coder is a minimal libxml2-based renderer rather than a wrapper
+# around librsvg. That built-in coder cannot handle SVGs with an embedded
+# base64-encoded raster <image> element (common in diagrams exported from
+# draw.io/diagrams.net): it fails with
+#   "convert-im6.q16: unable to open image `image/png;base64,...'"
+# because it tries to open the data-URI payload as if it were a file path.
+# `rsvg-convert` (from librsvg2-bin) handles the same file correctly.
+#
+# Route .svg sources through rsvg-convert directly; everything else (webp,
+# gif, pdf, ...) goes through ImageMagick's `convert` as before — webp support
+# is compiled into this ImageMagick build, so that path needs no delegate.
+set -euo pipefail
+
+# sphinx.ext.imgconverter's is_available() probes the converter with a
+# single-arg call (`im-convert -version`) before ever doing a real
+# conversion. Delegate straight to ImageMagick's own -version so the probe
+# succeeds — is_available()'s result is cached at the class level for the
+# whole build, so a failed probe here silently disables ALL conversion
+# (webp included), not just SVG.
+if [ "$#" -lt 2 ]; then
+    exec convert "$@"
+fi
+
+src=$1
+dst=$2
+
+# Strip ImageMagick's trailing frame-index suffix, e.g.
+# "/path/to/file.svg[0]" -> "/path/to/file.svg".
+plain_src=${src%\[*\]}
+
+case "$plain_src" in
+    *.svg|*.SVG)
+        exec rsvg-convert -o "$dst" "$plain_src"
+        ;;
+    *)
+        exec convert "$src" "$dst"
+        ;;
+esac
diff --git a/docs/conf.py b/docs/conf.py
index cefd1d84..c61b8984 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -53,6 +53,18 @@ extensions = ['sphinx.ext.intersphinx',
               'sphinx.ext.todo',
               'sphinx.ext.ifconfig',
               'sphinx.ext.graphviz',
+              # LaTeX-only: converts image formats the LaTeX/PDF builder can't
+              # embed natively (webp, svg, ...) to PNG at build time. The
+              # LaTeX builder's supported_image_types is ['application/pdf',
+              # 'image/png', 'image/jpeg'] — without this, unsupported
+              # images (nearly all of ours are .webp) are silently dropped
+              # from the PDF output. No effect on the HTML builder, which
+              # supports webp/svg natively in the browser; imgconverter
+              # only fires post-transforms when the active builder's
+              # supported_image_types doesn't already cover the source
+              # format. See `image_converter` below + docker/im-convert.sh
+              # for the conversion command this depends on.
+              'sphinx.ext.imgconverter',
               'notfound.extension',
               'autosectionlabel',
               'myst_parser',
@@ -62,6 +74,20 @@ extensions = ['sphinx.ext.intersphinx',
               'sphinx_sitemap',
 ]
 
+# sphinx.ext.imgconverter: use a thin wrapper (docker/im-convert.sh, installed
+# on PATH as `im-convert`) instead of ImageMagick's `convert` directly.
+# Debian's `imagemagick` package is built --without-rsvg, so its built-in SVG
+# coder (a minimal libxml2-based renderer, not a librsvg wrapper) can't
+# rasterize SVGs that embed a base64 raster <image> element — common in
+# diagrams exported from draw.io/diagrams.net — and fails with "unable to
+# open image `image/png;base64,...'". The wrapper routes .svg sources to
+# `rsvg-convert` (from librsvg2-bin) directly and everything else (webp,
+# gif, pdf, ...) through ImageMagick's `convert` as usual. If `im-convert`
+# isn't on PATH (e.g. a build environment other than docker/Dockerfile),
+# imgconverter's own `is_available()` check logs a warning and skips
+# conversion rather than failing the build.
+image_converter = 'im-convert'
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']