Sphinx执行make html时模块找不到，导入方式致脚本与文档冲突

项目结构 #

gui
├── src
│   └── gui
│       ├── __init__.py
│       ├── neuro_gui.py
│       └── listen.py
└── docs
    ├── _build
    ├── conf.py
    └── etc

conf.py 配置 #

import os 
import sys
sys.path.insert(0, os.path.abspath('..'))
sys.path.insert(0, os.path.abspath('../src/'))
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']
napoleon_google_docstring = False

操作流程与问题 #

1. 在根目录gui下执行命令：

   sphinx-apidoc -o docs src\gui src\gui\ui_*
   

   成功在docs目录生成gui.rst和modules.rst文件。
2. 进入docs目录执行make html，Sphinx能正常为listen.py生成文档，但neuro_gui.py中的导入语句from listen import Listener触发报错：

   WARNING: autodoc: failed to import module 'gui' from module 'gui'; the following exception was raised:
   No module named 'listen'

尝试过的方案及问题 #

• 使用相对导入from .listen import listener：Sphinx文档生成正常，但直接运行脚本时报错：

  ImportError: attempted relative import with no known parent package
  

• 在__init__.py中添加from __future__ import absolute_import并改用绝对导入from gui.listen import listener：Sphinx能正常生成文档，但脚本运行时报错：

  ModuleNotFoundError: No module named 'gui'
  

• 另外发现conf.py中sys.path.insert(0, os.path.abspath('..'))无实际作用，仅保留sys.path.insert(0, os.path.abspath('../src/'))即可。

解决方案 #

1. 统一用绝对导入，通过包安装或环境变量解决脚本运行问题

保持neuro_gui.py里的导入为绝对导入：

from gui.listen import Listener

然后二选一解决脚本运行问题：

• 本地可编辑安装包（推荐）：在根目录gui下执行

  pip install -e .
  

  这样Python会把src下的gui包纳入全局可导入范围，不管在哪运行脚本都不会报错。
• 临时设置PYTHONPATH：
  Windows（cmd）：

  set PYTHONPATH=.\src
  python src\gui\neuro_gui.py
  

  Linux/macOS：

  export PYTHONPATH=./src
  python src/gui/neuro_gui.py
  

2. 优化Sphinx配置（可选）

把conf.py里的路径设置改成更明确的写法，避免路径歧义：

import os
import sys
# 直接定位到src目录
sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '../src')))
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']
napoleon_google_docstring = False

3. 使用统一入口脚本（更规范）

在src目录下新建main.py作为程序入口：

from gui.neuro_gui import 你的主类或启动函数

if __name__ == "__main__":
    # 启动GUI逻辑
    你的启动函数()

然后运行python src/main.py，配合上面的包安装或环境变量设置，既能正常运行程序，也不影响Sphinx生成文档。

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