使用Sphinx文档化子项目遇ModuleNotFoundError：helperfunc找不到

问题原因 #

你遇到的警告是因为Sphinx在导入nfz_extraction.nfzOcr时，无法解析同目录下helperfunc的导入路径。虽然nfzOcr和helperfunc在同一目录，但你使用的from helperfunc import...是绝对导入，而Sphinx通过sys.path.insert(0, os.path.abspath(".."))把项目根目录加入路径后，会尝试从根目录查找helperfunc模块，而非nfz_extraction子目录下的同名模块，因此找不到。

解决方案 #

方案1：改用相对导入（推荐） #

修改nfzOcr.py中的导入语句为相对当前包的形式：

from .helperfunc import dbDeleteRow, dbInsert, dbSelect

这种方式明确指定从当前模块所在的包（即nfz_extraction）中导入helperfunc，无论在项目运行还是Sphinx文档生成时都能正确解析路径。

方案2：调整conf.py的路径配置 #

如果不想修改业务代码，可以在conf.py中把nfz_extraction目录直接加入sys.path：

import os
import sys
# 加入项目根目录
sys.path.insert(0, os.path.abspath(".."))
# 额外加入nfz_extraction目录
sys.path.insert(0, os.path.abspath("../nfz_extraction"))

这样Sphinx就能直接找到helperfunc模块，但这种方式可能会导致模块命名冲突，不如相对导入规范。

方案3：确保项目是可安装的包结构 #

如果你的项目是标准的Python包（包含setup.py或pyproject.toml），可以先在开发模式下安装项目：

pip install -e .

这样Python会把项目包加入全局路径，Sphinx就能正常解析所有内部导入，无需额外调整sys.path。

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