如何在Sphinx/ReStructured Text中保持缩放图片的宽高比

问题描述 #

用Sphinx构建文档时，未缩放的图片表现正常：

.. figure:: images/manual_exposure1.png

在Firefox中左对齐，宽高比锁定，调整网页宽度或在移动端查看时，会按可用空间等比缩小。

但添加:scale: 50%后：

.. figure:: images/manual_exposure1.png
    :scale: 50%

图片在网页缩到特定宽度时会被挤压——保持高度的同时横向压缩，破坏宽高比。

我尝试过自定义CSS类，但效果不符合预期：

.. raw:: html

   <style>
       img.custom-class {
           max-width: 60%;
           height: auto;
           align: left;
       }
   </style>

这个CSS会把图片锁定为页面宽度的60%，而:scale版本是先达到最大缩放尺寸，再随页面宽度缩小占比，两者逻辑不一致。

请问实现缩放图片与未缩放图片一致表现的最佳方式是什么？是预先缩放图片，还是通过Sphinx或合适的CSS实现？

补充：不同窗口宽度下的行为截图（从宽到窄）：

解决方案 #

1. 自定义CSS替代:scale（推荐） #

问题根源是Sphinx的:scale参数会同时给图片设置固定的width和height百分比，浏览器无法在窗口缩小时自动调整比例。而未缩放图片的默认样式是max-width:100%; height:auto;，因此能自适应。

我们可以通过自定义CSS类实现和:scale相同的初始缩放比例，同时保留自适应特性：

/* 在 Sphinx 的自定义 CSS 文件（比如 _static/custom.css）中添加 */
.figure-scaled-50 img {
    max-width: 50%; /* 对应原scale的50%比例 */
    height: auto;
    align-self: flex-start; /* 保持左对齐 */
}

使用时给figure添加自定义类，不要用:scale参数：

.. figure:: images/manual_exposure1.png
    :class: figure-scaled-50

这样图片初始最大宽度是容器的50%，窗口缩小时会自动等比缩放，和未缩放图片的表现完全一致。

2. 预先缩放图片 #

如果不想修改CSS，可以用图片处理工具（如ImageMagick、Photoshop）将图片预先缩放到原尺寸的目标比例（比如50%），然后直接使用未缩放的figure声明：

.. figure:: images/manual_exposure1_scaled.png

这种方式天然继承未缩放图片的自适应特性，缺点是需要额外维护缩放后的图片文件，后续调整比例时要重新处理图片。

总结 #

优先选择自定义CSS方案，无需修改原始图片，比例调整更灵活，维护成本更低。

内容的提问来源于stack exchange，提问作者Douglas B