python-2.7 - Sphinx - 引用来自不同位置的图像

Question

我正在使用 Python Sphinx(通过 ReadTheDocs)。

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

我的文件夹层次结构是:

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

和 README.rst 模块 1 引用图像:

.. image:: _static/myimage.jpg

当我查看模块 1(在 GitHub 内)的 README 文件时 - 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 文档.

When used within Sphinx, the file name given (here gnu.png) must either be relative to the source file, or absolute which means that they are relative to the top source directory. For example, the file sketch/spam.rst could refer to the image images/spam.png as ../images/spam.png or /images/spam.png.