Sphinx递归autosummary无法导入模块问题求助

1. 路径配置验证 #

你在docs/source/conf.py里使用的os.path.abspath('../..')理论上指向my_wd目录，但可以先添加打印语句确认路径是否正确：

import os
import sys
print(os.path.abspath('../..'))  # 执行sphinx-build时查看输出的绝对路径
sys.path.insert(0, os.path.abspath('../..'))

如果输出不是my_wd的绝对路径，说明相对路径解析出现偏差，改用绝对路径直接写入更稳妥。

2. 检查库的可导入性 #

• 确保my_library目录下存在__init__.py文件（空文件即可），否则Python不会将其识别为可导入的包。
• 在my_wd目录下打开Python终端，执行import my_library，如果报错，说明不是Sphinx的问题，先解决库本身的可导入性问题。

3. 排查环境路径冲突 #

有时候虚拟环境或当前Python环境的site-packages中存在重名包，会干扰Sphinx的导入逻辑。可以在conf.py中打印路径列表确认：

print(sys.path)

确保my_wd路径排在列表最前面，避免被其他路径的同名包覆盖。

4. 模块自身导入问题 #

日志中的ValueError大概率是因为你的模块导入了未安装的依赖，或者模块本身在导入阶段就会抛出错误。单独测试每个模块：

# 在my_wd目录下执行
python -c "import my_library.你的模块名"

如果报错，先修复模块自身的导入错误，再重新运行Sphinx。

5. autosummary配置与格式兼容性 #

• 检查index.md中的autosummary语法是否正确，递归生成的标准配置应为：

  .. autosummary::
     :toctree: _autosummary
     :recursive:
  
     my_library
  

• 若使用markdown格式的索引文件，确保你使用的Sphinx markdown解析器（如m2r2）支持rst指令，也可以临时改用rst格式的index.rst测试，排除格式兼容性问题。

6. 自定义模板干扰 #

暂时移除_templates目录下的自定义模板，使用默认模板重新构建。如果能正常生成文档，说明自定义模板存在语法或逻辑问题，需要排查模板代码。

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