Sphinx autodoc导入问题：Python项目模块无法识别

问题背景 #

项目目录结构：

b_tool
 |
 |--b.py
 |
 |--sub
 |   |
 |   |--sub.py
 |
 |--Doc
     |
     |--Sphinx

主文件b.py位于C:\b_tool\b.py，通过from b_tool.sub.sub import Subclass的绝对路径方式导入子模块，在C:目录执行python -m b_tool.b可正常运行。但在C:\b_tool\Docs\Sphinx目录执行make html时，出现如下错误：

WARNING: autodoc: failed to import module 'b'; the following exception was raised:
No module named 'b_tool'

当前conf.py已添加路径配置，但问题未解决。

解决方案 #

修改conf.py中的路径配置，将Python的模块搜索路径指向b_tool所在的父目录（即C:\），具体修改如下：

project = 'B'
copyright = '2023, John Doe'
author = 'John Doe'
    
import os
import sys
# 替换原路径配置，指向b_tool的父目录
sys.path.insert(0, os.path.abspath('../../..'))

extensions = ['sphinx.ext.autodoc']

templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

原因说明 #

当前conf.py位于C:\b_tool\Docs\Sphinx，原配置中的os.path.abspath('../..')会解析为C:\b_tool，但Python需要找到b_tool这个包的父目录，才能正确识别b_tool.sub.sub这种绝对导入语法。调整路径为../../..后，解析结果为C:\，和你运行python -m b_tool.b时的工作目录一致，Sphinx就能正确找到b_tool模块。

如果担心层级计数出错，也可以用更直观的写法：

# 明确定位到b_tool的父目录
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))

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