If width is not explicitly set for images in the documentation, an implicit width of 80% page width is imposed for the PDF version (see doc/external/extensions/pdfimgsize.py), which will cause images with low aspect ratio to potentially cover several pages and may cause a crash.
An updated solution to this conundrum has been introduced in commit r39236. Since there seems to be an inconsistency in DPI assumptions, as in 72 vs 96, we apply an implicit scale of 3/4 on all SVGs lacking explicit width/height/scale. Looking at the function size_for_node() in https://github.com/rst2pdf/rst2pdf/blob/main/rst2pdf/image.py, it is not obvious why large SVGs that are scaled down prior to our 3/4 factor, are still rendered above 75% width. However, both large and smaller images appear fine in the resulting document, so this is sufficient for now.
Things have got a bit convoluted with this bug here, so we need to reassess what the goals and obstacles are. We generally design our images to look good in the HTML version of the documentation. So ideally, we want the PDF version to look the same. That should mean the relationship between text size and image pixel size should be the same between HTML and PDF. The two misbehaviours we've identified in rst2pdf are: * It assumes a DPI of 72 for SVGs, whilst browsers assume 96 (i.e. SVG pixel is the same as CSS pixel) * It respects the DPI information of PNG images, whilst browsers ignore it (again, rendering one PNG pixel as one CSS pixel) We originally worked around the last point by scaling all images to 80% of the page width. But this method fails if the image is too narrow as it will be scaled to cover more than one page. We've since also tried to work around the first bug. Which happened to solve the "narrow" side effect as the only narrow image we currently have is an SVG. We should do more proper workarounds or fixes for these, and report these problems upstream.
