如何在Sphinx中处理导入类？包相对导入报错求助

问题回顾 #

你遇到的情况是：包内模块使用相对导入（比如a.py里的from .b import B）在正常功能和测试中都没问题，但用Sphinx执行make html构建文档时，触发了ValueError: Attempted relative import in non-package错误。

核心原因 #

Sphinx在构建文档时，会尝试直接加载你的模块文件。如果你的包目录没有被添加到Python的sys.path中，Sphinx会把a.py当成一个独立的脚本，而不是包的一部分——这时候相对导入就会失效，因为相对导入仅适用于作为包组件导入的模块。

解决方案 #

最直接有效的方法是修改Sphinx的配置文件，把包的根目录加入Python路径，让Sphinx能以包的方式导入模块：

1. 打开docs/source/conf.py文件

2. 在文件开头添加以下代码（路径根据你的目录结构调整，这里假设conf.py在docs/source，包在项目根目录的package文件夹）：

   import os
   import sys
   # 把包的父目录（项目根目录）加入sys.path
   sys.path.insert(0, os.path.abspath('../../'))
   

3. 确保你的rst文档里的automodule指令是从包名开始的，比如：

   .. automodule:: package.a
      :members:
      :show-inheritance:
   

   而不是直接写.. automodule:: a

4. 重新执行make html，应该就能正常构建文档了。

补充说明 #

如果不想修改sys.path，还有一个备选方案：把模块里的相对导入改成绝对导入（比如from package.b import B），但这种方式会让包的耦合性变强，不推荐在包内部使用，所以优先选择修改Sphinx配置的方法。

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