Sphinx执行doctest报ModuleNotFoundError无法导入lumache

错误根因 #

路径配置与实际目录结构不匹配：

• 你的lumache.py和conf.py同处于docs/source/目录下
• 现有配置pathlib.Path(__file__).parents[2]会从conf.py所在位置向上回溯2级目录，最终指向docs文件夹的上一级目录（即你执行命令时所处盘符的根目录C:\），该路径下不存在lumache.py，Python扫描模块时无法找到对应文件，因此抛出导入错误。

注：官方教程中的parents[2]配置匹配的是「源码文件与docs文件夹同级、存放在项目根目录」的结构，和你当前把lumache.py放在source目录下的结构不一致，直接照搬会出现路径偏差。

修复方案 #

二选一即可：

方案1：适配现有目录结构 #

修改conf.py中的路径配置，将lumache.py所在的source目录加入系统路径，把原有路径配置行替换为：

sys.path.insert(0, pathlib.Path(__file__).parent.resolve().as_posix())

（pathlib.Path(__file__).parent和parents[0]效果完全一致，都是指向conf.py所在的当前目录）

方案2：对齐官方目录规范 #

保留conf.py的原有配置不变，将lumache.py从docs/source/目录移动到docs/文件夹的上一级（与docs文件夹同级的项目根目录），即可匹配官方配置的路径扫描规则。

验证 #

修改完成后回到C:\docs目录重新执行make doctest命令，即可正常加载lumache.py完成测试。

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