Read the Docs无法渲染README.md图片，本地构建正常求解决

本地构建Sphinx文档时，README.md中的图片![Illustration](./figures/fig.png)可正常渲染，但在Read the Docs（RTD）构建时提示image file not readable，图片无法显示。相关配置与目录结构如下：

目录结构 #

├───docs
│   │   conf.py
│   │   index.rst
│   │   README.rst
│   │   requirements.txt
│   │
│   ├───figures (符号链接至项目根目录figures文件夹)
├───figures
│   └── fig.png
└───README.md

index.rst配置 #

.. include:: ../README.md
   :parser: myst_parser.sphinx_

.. toctree::
   :maxdepth: 1

   README.rst

.. toctree::
   :maxdepth: 1
   :caption: Tutorial:
   :glob:

   notebook/*
 
.. toctree::
   :maxdepth: 2
   :caption: API:
   :glob:

   autoapi/index

方法1：调整图片路径 #

由于README.md被include至docs/index.rst，构建上下文为docs目录，而RTD默认不支持符号链接，直接将README.md中的图片路径改为指向根目录的相对路径：

![Illustration](../figures/fig.png)

此方法无需额外配置，只要仓库根目录的figures文件夹存在，RTD拉取代码时会自动包含该目录，即可正常加载图片。

方法2：在conf.py中配置图片搜索路径 #

在docs/conf.py中添加以下代码，将根目录的figures添加到Sphinx的静态文件搜索路径：

import os
import sys
sys.path.insert(0, os.path.abspath('..'))

# 添加图片目录到静态资源路径
html_static_path = ['_static', '../figures']

配置后，原README.md中的./figures/fig.png路径会被Sphinx识别，无需修改图片链接。

方法3：构建前复制图片目录 #

在RTD的构建脚本中添加步骤，将根目录的figures复制到docs目录下，避免符号链接依赖。可通过项目根目录的.readthedocs.yaml配置：

build:
  os: ubuntu-22.04
  tools:
    python: "3.10"
  jobs:
    pre_build:
      - cp -r ../figures ./docs/

此方法确保docs/figures为实际文件目录，RTD可正常读取。

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