【问题标题】：How do I display an image in Sphinx docs from a Python docstring?如何在 Python 文档字符串中的 Sphinx 文档中显示图像？
【发布时间】：2020-04-27 00:58:16
【问题描述】：

Python 文档字符串图像嵌入

在 Python 文档字符串中，我有一个 reStructuredText 指令来显示图像：

.. image:: ./images/code_quality.png

我得到一个小图标和一个路径，而不是图像：

_images/code_quality.png

Screen clip of link shown instead of the image I want to show.

我也试过这个：

.. image:: images/code_quality.png

还有这个：

.. image:: https://imgs.xkcd.com/comics/code_quality.png
   :alt: code_quality

使用图形而不是图像只是将相同的输出居中。

.. figure:: images/code_quality.png

如果我将它从文档字符串中取出并放在 .rst 文件中，它也不起作用。

图像被复制到 _static 目录中，因为它应该由 Sphinx 复制。任何其他形式的链接都会引发错误。我在指令前后有两个空行。

所有其他文档字符串都正确呈现，包括包含图像链接的文档字符串的其余部分。我没有其他要渲染的图像，但我之前在另一个模块中尝试过一次，但它也没有工作。

我正在使用 autodoc 来扫描 Python 模块的文档字符串。我使用的是 Windows 10，Chrome 是我的主要浏览器。它也不适用于我尝试过的任何其他浏览器。

有一些建议可以查看此答案： Is it possible embed pictures into docstring in Python?

我正在使用图像指令。
我的路径是正确的。
相对路径和完整路径都不会导致渲染图像。
我没有在这个项目中使用 PyCharm，我使用的是 VS Code。
除了图像问题之外，我的文档呈现良好。

shell 输出：

\docs>make html
Running Sphinx v2.4.4
loading translations [en]... done
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 11 source files that are out of date
updating environment: [new config] 11 added, 0 changed, 0 removed
reading sources... [100%] user_guide
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] user_guide
generating indices...  genindex py-modindexdone
writing additional pages...  searchdone
copying images... [100%] images/code_quality.png
copying static files... ... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.

The HTML pages are in build\html.

HTML 输出的图像部分是：

<img alt="_images/code_quality.png" tedc="_images/code_quality.png" />

（'tedc' 是我在项目的根 setup.py 模块中定义的应用程序的名称。）

GitHub Repo

这是我尝试通过创建一个结构与我的生产项目结构相同的项目来重新创建图像指令在 Sphinx 中无法正常工作的问题。

我的生产代码是从根目录调用的，模块位于包中。

我的文档位于 docs 目录中，与此处显示的相同。

我用的是虚拟环境，和这里一样。

我使用的库比这里使用的要多得多。

我正在使用 Python 3.8.2

我在练习中没有发现任何东西可以帮助解释为什么图像指令在我的生产代码中不起作用。我的生产代码使用相同的指令。

【问题讨论】：

愚蠢的问题，但路径 ./images/code_quality.png 正确吗？
重复stackoverflow.com/questions/45739474/…
这能回答你的问题吗？ Is it possible embed pictures into docstring in Python?
@jhachtel img HTML 标签缺少 src 属性，tedc 不是 img 的有效 HTML 属性。我不知道你是如何从你提供的第一个代码中得到那个 HTML 的，它应该提供一个 src 属性。您必须具有src 属性，否则图像将不会显示。
我尝试使用您的存储库复制它，但无法复制。我认为您对setup.py 中的name='tedc' 有所了解。您的存储库将其命名为 app，但我没有看到 app 而不是 src 的图像属性。我从来没有见过这样的事情。我唯一的建议是扔掉你的虚拟环境和 Sphinx 构建目录，重新创建你的虚拟环境，安装需求，然后再次构建文档。

标签： python python-sphinx restructuredtext docstring

【解决方案1】：

在我尝试重现此问题但未能成功后，我建议 OP 尝试删除虚拟环境和 docs 构建目录，并重新创建他们的虚拟环境，安装需求，并再次构建 docs。这解决了问题。

【讨论】：

现在完美运行。谢谢@StevePiercy。