使用Sphinx/RST的include指令时图片缺失问题求助

针对你遇到的include指令能正常引入RST文件，但引入文件内的图片却无法显示的问题，我之前处理过类似的跨目录引用场景，结合你的项目结构和已经尝试过的方法，给你几个可行的解决思路：

先明确你的场景 #

你的项目结构简化后如下：

/documentation
    /master_doc
        /source
            pointer_file.rst  # 这里用include引入外部文件：include:: ../../documents/doc_a/source/file.rst
/documents
    /doc_a
        /source
            /images
                picture.jpg
            file.rst  # 内部图片引用：.. figure:: images/picture.jpg

从doc_a目录构建时文本和图片都正常，但从master_doc目录构建时仅显示文本、图片丢失，且你不想重复存放图片。你之前尝试的带开头/的绝对路径无效，那可以试试下面这些方法：

方法1：用conf.py的rst_prolog定义全局路径变量 #

这是我最常用的通用解决方案，能从根本上解决跨目录路径问题：

1. 打开master_doc/source/conf.py，添加以下代码（注意路径要根据实际结构调整，确保生成的是本地文件系统的绝对路径）：

import os

# 计算doc_a图片目录的绝对路径
doc_a_images_abs_path = os.path.abspath('../../documents/doc_a/source/images')

# 在rst_prolog中定义可替换的路径变量
rst_prolog = f"""
.. |doc_a_images| replace:: {doc_a_images_abs_path}
"""

2. 修改doc_a/source/file.rst里的图片引用：

.. figure:: |doc_a_images|/picture.jpg
   :alt: 图片描述文本

这样不管从哪个目录构建Sphinx，都会自动把|doc_a_images|替换成图片的绝对路径，确保能正确定位到图片文件。

方法2：配置html_static_path（仅针对HTML输出） #

如果只需要生成HTML格式的文档，可以把doc_a的图片目录添加到Sphinx的静态资源路径：

1. 在master_doc/source/conf.py中修改静态资源配置：

html_static_path = ['_static', '../../documents/doc_a/source/images']

2. 然后修改file.rst里的图片引用为：

.. figure:: /picture.jpg

⚠️ 注意：如果多个目录存在重名图片，这个方法会导致资源冲突，需要确保所有图片文件名唯一。

方法3：使用基于构建根目录的相对路径 #

你之前尝试的是带开头/的"网站根目录绝对路径"，而非本地文件系统的路径，试试不带开头/的、基于master_doc/source目录的相对路径：

.. figure:: ../../documents/doc_a/source/images/picture.jpg

你可以先在终端里从master_doc/source目录执行ls ../../documents/doc_a/source/images/picture.jpg，验证这个路径是否能正确找到图片。

方法4：使用substitutions结合rst_epilog #

和方法1原理类似，只是把替换规则放在文档末尾加载，效果一致：

1. 在conf.py中添加：

import os

doc_a_img_root = os.path.abspath('../../documents/doc_a/source/images')
rst_epilog = f".. |doc_a_img_root| replace:: {doc_a_img_root}"

2. 在file.rst中使用变量引用图片：

.. figure:: |doc_a_img_root|/picture.jpg

这些方法都不需要重复存放图片，你可以根据自己的输出格式需求选择最合适的方案。比如方法1通用性最强，适合所有输出格式；方法2适合只需要HTML文档的场景。

内容的提问来源于stack exchange，提问作者Fiona Hanington