From b78ccb662b2359a2cb5f60c4040c30004b43a412 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Fri, 10 Jul 2026 19:01:35 +0300 Subject: docs-infra: convert webp/svg images for PDF builds (sphinx.ext.imgconverter + ImageMagick/librsvg) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 🤖 Generated by [robots](https://vyos.io) --- docs/conf.py | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) (limited to 'docs') 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 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'] -- cgit v1.2.3