将可点击的 SVG 图像插入 Sphinx 文档答案

【问题标题】：Insert clickable SVG image into Sphinx documentation将可点击的 SVG 图像插入 Sphinx 文档
【发布时间】：2016-04-19 02:11:57
【问题描述】：

我有几个节点的 SVG 图像文件，每个节点都与 URL 相关联。如果我直接在浏览器中打开这个文件，我可以点击每个节点，它会打开不同的 URL。但是，当我在 Sphinx 文档中使用此图片时，它不起作用 - 图片呈现为一个整体，因此我需要通过 View Image 打开它，然后才能单击节点。

我正在使用标准图像指令：

.. image:: myfile.svg

可能我需要使用其他东西？

【问题讨论】：

the graphviz extension 中也有类似的问题。我猜这个问题可能在 Docutils 中，这是构建 Sphinx 的基础。
我不认为这是一个错误——使用不同的方式嵌入 svg 有不同的问题。见here。您可以在 Docutils 邮件列表中询问一些 hep 并可能请求此功能，或者您可以编写一个 sphinx 扩展以按照您想要的方式包含 svg 图像。
您找到解决方案了吗？

标签： python-sphinx restructuredtext read-the-docs

【解决方案1】：

我喜欢这种方式

.. raw:: html

    <a href="https://www.google.com/">
        <img src="https://img.shields.io/static/v1?&style=plastic&logo=appveyor&label=Google&message=link2google&color=FF0000" alt="No message"/></a>

【讨论】：

【解决方案2】：

为了在 sphinx 中包含可点击的 svg 链接，我执行了以下操作：

.. raw:: html
    :file: ../graphs/pymedphys_analysis.gamma.svg

见：

https://raw.githubusercontent.com/pymedphys/pymedphys/1915b9496e93782bdac7dcebff7e26e470e5ff57/docs/graphs/graphs.rst

这让我可以在导入的样式表中编写以下内容：

svg {
    width: 100%;
}

https://github.com/pymedphys/pymedphys/blob/f4d404fa1cf3f551c4aa80ef27438f418c61a436/docs/_static/style.css

这使得 svg 根据需要适合容器。

见：

https://pymedphys.com/developer/dependencies.html#pymedphys

【讨论】：

【解决方案3】：

我可能误解了 OP 的要求，但为什么不将 SVG 作为 html 包含在 sphinx 文档中呢？这似乎对我有用：

.. raw:: html
    :file: images/image.svg

【讨论】：

这个答案对我有用。我很难使接受的答案起作用。我正在使用狮身人面像 Version: 4.0.1

【解决方案4】：

我自己仍在寻找更好的解决方案，但我遇到了同样的问题并使用了这个解决方法。

您可以使用下载指令为用户提供文件的链接。

:download:`svg <images/image.svg>`

【讨论】：

【解决方案5】：

Sphinx 为图像生成<img> 标签，这在大多数情况下是有意义的。但是，要使 svg 中的链接可点击，您应该使用 <object> 标签，即：

.. raw:: html

    <object data="myfile.svg" type="image/svg+xml"></object>

（关于您链接到的GitHub issue，我认为Sphinx 在这里没有什么可以做的——实际上是quite complicated——没有在.. image 指令中引入一个新选项，让用户指定是否呈现为img 或object 标签。）

【讨论】：

@ruslo 我认为 sphinx 维护人员将您的错误报告视为您提议将 all .. image svgs 呈现为 object 标记。这可能会破坏其他一些image options，例如:width 和:height。但是，如果您只是编写自己的原始 HTML，则与您无关。

【解决方案6】：

一个简单的解决方案是在此.. image:: myfile.svg 命令中添加指向 svg 文件的链接：

.. image:: myfile.svg
   :target: _images/myfile.svg

请注意检查生成 html 文件时复制图像的相对目录。默认情况下，应该是_images/。

这样，您可以单击 SVG 文件，在普通页面中查看它，然后像往常一样单击它（不是完美的解决方案，但仍然......）。

【讨论】：

@ruslo 我认为添加这样的目标会有所帮助，因为新手用户的反应是点击图像，而不是Right Click → View Image。