如何在包含某些图像的相对路径的 sphinx 中呈现 readme.md

Question

我正在使用 m2r2 使用狮身人面像呈现 html 文档。 我的文件夹结构是

project
  |_ docs
      |_ sphinx root
  |_ README.md
  |_ image_to_include_in_readme.png

README.md 看起来像这样：

# This is heading

Some text. refer to the image : [Image](image_to_include_in_readme.png)

但是这张图片无法从 sphinx 根文件夹中读取。

我能够在 html 中使用

mdinclude

指令正确渲染 readme.md，但不渲染图像。我越来越

 WARNING: image file not readable:

我知道我可以将图像复制到构建文件夹中，但我不想那样做。我该如何解决？

Answer 1

ChatGPT-4 建议将这些行添加到 conf.py：

# Copy ./examples/results images into documentation so they show up when
# markdown files with relative paths are transcluded
import os
import shutil


def copy_examples(app, docname):
    if app.builder.name == 'html':
        output_dir = os.path.join(app.outdir, 'examples', 'results')
        source_dir = os.path.join(app.srcdir, '..', 'examples', 'results')
        if not os.path.exists(output_dir):
            os.makedirs(os.path.join(app.outdir, 'examples'))
            shutil.copytree(source_dir, output_dir)


def setup(app):
    app.connect('build-finished', copy_examples)

现在文件已复制并存在于

https://endolith.github.io/elsim/examples/results/Merrill_1984_Figure_1._25_voters,_10000_iterations.png

，README.md 文件的相对链接为：

![](./examples/results/Merrill_1984_Figure_1._25_voters,_10000_iterations.png)

包含在生产线中

.. mdinclude:: ../README.md

转换为 html:

<a class="reference external image-reference" href="./examples/results/Merrill_1984_Figure_1._25_voters,_10000_iterations.png">
<img alt="" src="examples/results/Merrill_1984_Figure_1._25_voters,_10000_iterations.png">
</a>

转到被复制的文件。

这是理想的解决方案吗？我不知道，但它有效，尽管

make html

还在说：

reading sources... [100%] index
../README.md:: WARNING: image file not readable: examples/results/Merrill_1984_Figure_1._25_voters,_10000_iterations.png