参考不同位置的图像

Question

我正在使用 Python Sphinx（通过 ReadTheDocs）。

我有一个包含一些子模块的存储库，我正在尝试创建一个统一的文档，但仍然单独保留每个模块中的 docs 资产。

我的文件夹层次结构是：

MyProject
  docs
    index.rst
    module_1_link.rst
      _static
        <more irrelevant assets...>               
  module_1
    docs
      README.rst
      _static
        myimage.png

index.rst

文件如下所示：

.. toctree::
    :caption: Module1
    module_1_link

文件

module_1_link.rst

仅包含模块1的自述文件的链接：

.. include:: ../module1/docs/README.rst

模块 1 的

README.rst

引用了图像：

.. image:: _static/myimage.jpg

当我查看模块 1 的 README 文件（在 GitHub 内）时 -

myimage.png

完美显示。

但是，当我通过 Sphinx 运行文档时，我得到：

警告：图像文件不可读：_static/myimage.jpg

我找不到从 README 文件和 Sphinx 渲染的索引文件中引用相同图像并在两个地方看到它的方法。

Answer 1

将对

README.rst

中的图像的引用更改为相对于文档根目录。

.. image:: /module1/docs/_static/myimage.jpg

另请参阅有关 图像路径的 Sphinx 文档。

在 Sphinx 中使用时，给定的文件名（此处

gnu.png

）必须是相对于源文件的，或者是绝对的，这意味着它们相对于顶级源目录。例如，文件

sketch/spam.rst

可以将图像

images/spam.png

引用为

../images/spam.png

或

/images/spam.png

。