如何在來自 Python 文檔字符串的 Sphinx 文檔中顯示圖像？

Question

Python 文檔字符串圖像嵌入

在 Python 文檔字符串中，我有一個 reStructuredText 指令來顯示圖像：

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

我得到一個小圖標和一個路徑，而不是圖像：

_images/code_quality.png

顯示鏈接的屏幕剪輯，而不是我要顯示的圖像。

我也試過這個：

.. image:: images/code_quality.png

和這個：

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

使用圖形而不是圖像只是將相同的 output 居中。

.. figure:: images/code_quality.png

如果我將它從文檔字符串中取出並將其放入一個 .rst 文件中，它也不起作用。

圖像被復制到 _static 目錄中，因為它應該由 Sphinx 復制。 任何其他形式的鏈接都會引發錯誤。 我在指令前后有兩個空行。

所有其他文檔字符串都正確呈現，包括包含圖像鏈接的文檔字符串的 rest。 我沒有其他要渲染的圖像，但我之前在另一個模塊中嘗試過一次，但它也沒有工作。

我正在使用 autodoc 掃描 Python 模塊的文檔字符串。 我在 Windows 10 上，Chrome 是我的主要瀏覽器。 它也不適用於我嘗試過的任何其他瀏覽器。

---

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

• 我正在使用圖像指令。
• 我的路徑是正確的。
• 相對路徑和完整路徑都不會導致渲染圖像。
• 我沒有在這個項目中使用 PyCharm，我使用的是 VS Code。
• 除了圖像問題之外，我的文檔還可以很好地呈現。

---

Shell output 制造商：

\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 output 的圖像部分是：

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

（'tedc' 是我在項目的根 setup.py 模塊中定義的應用程序的名稱。）

---

GitHub 回購

這是我嘗試通過創建一個結構與我的生產項目結構相同的項目來重新創建圖像指令在 Sphinx 中無法正常工作的問題。

我的生產代碼是從根調用的，模塊位於包中。

我的文檔位於 docs 目錄中，與此處介紹的相同。

我使用虛擬環境，和這里一樣。

我使用的庫比這里使用的要多得多。

我正在使用 Python 3.8.2

我在練習中沒有發現任何有助於解釋為什么圖像指令在我的生產代碼中不起作用的東西。 我的生產代碼使用相同的指令。

Answer 1

在我嘗試重現此問題但未能成功后，我建議 OP 嘗試刪除虛擬環境和 docs 構建目錄，並重新創建他們的虛擬環境，安裝需求並再次構建 docs。 這解決了這個問題。