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

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

2 files changed, 58 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