Sphinx - 参考来自不同位置的图像

Question

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

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

我的文件夹层次是：

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的README文件的链接：

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

模块1的README.rst引用图像：

.. image:: _static/myimage.jpg

当我查看模块1的README文件（在GitHub中）时，myimage.png显示完美。

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

 WARNING: image file not readable: _static/myimage.jpg

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

Answer 1

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

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

另见paths to images上的Sphinx文档。

在Sphinx中使用时，给定的文件名（此处为gnu.png）必须相对于源文件，或绝对值，这意味着它们相对于顶级源目录。例如，文件sketch/spam.rst可以将图像images/spam.png称为../images/spam.png或/images/spam.png。