Sphinx conf.py无法找到外部_utils模块类的问题求助

问题原因 #

执行make命令时工作目录是docs，Python默认的模块搜索路径（sys.path）里没有包含source目录，所以找不到_utils这个模块。

解决方案 #

1. 在conf.py中添加模块搜索路径

在conf.py的开头加入以下代码，把source目录添加到Python的模块搜索路径里：

import os
import sys
# 获取当前conf.py所在的source目录的绝对路径
sys.path.insert(0, os.path.abspath(os.path.dirname(__file__)))

之后再执行导入语句：

from _utils.utils import MyClass

2. 确保_utils目录是合法的Python模块

在_utils目录下创建一个空的__init__.py文件（Python 3.3+虽支持无__init__.py的命名空间包，但部分Sphinx环境可能需要显式声明），让Python把_utils识别为可导入的模块。

3. 验证路径是否正确（可选）

可以在conf.py里临时添加打印语句，确认source目录已被加入搜索路径：

print(sys.path)

执行make命令时查看控制台输出，检查source的绝对路径是否在列表中。

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