Sphinx本地autodoc构建成功但Read the Docs部署后页面全空求助

1. 补充项目根目录的Python导入配置 #

你当前的.readthedocs.yml仅安装了文档依赖，没有将项目根目录加入Python可导入路径，导致Sphinx的autodoc扩展在Read the Docs环境中无法找到根目录下的module1.py、module2.py、module3.py文件，最终生成空白页面。
修改.readthedocs.yml的python.install节点，添加项目本地安装配置：

# 完整修改后的readthedocs.yml示例
version: 2
sphinx:
  configuration: docs/conf.py
formats: all
python:
  version: 3.8
  install:
    - requirements: docs/requirements.txt
    # 新增以下两行，将项目根目录安装到Python环境
    - method: pip
      path: .

2. 补全依赖声明 #

你的docs/requirements.txt仅声明了主题依赖，没有明确指定Sphinx版本，Read the Docs默认使用的Sphinx版本可能和你本地版本不兼容，引发构建异常。需要在requirements.txt中添加和你本地版本一致的Sphinx约束：

sphinx==5.3.0 # 替换为你本地使用的Sphinx版本号
sphinx_rtd_theme==1.0.0

如果你的业务模块依赖其他第三方库，也需要同步添加到该文件中，避免autodoc导入模块失败。

3. 确认目录索引配置 #

检查docs/index.rst的toctree节点是否已正确关联三个模块的rst文件，示例配置如下：

MolOpt 文档
==========

.. toctree::
   :maxdepth: 2
   :caption: 模块列表

   module1
   module2
   module3

索引
====
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

验证修改 #

修改完成后先在本地清理缓存重新构建，确认本地构建正常后再提交代码触发Read the Docs重新构建即可：

cd docs
rm -rf _build
make html

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