Sphinx Autodoc导入模块失败：无法找到Camera模块求助

架构老林

2026-7-7

Sphinx Autodoc 模块导入错误排查

项目结构

Project
|
|--Main Folder
|    |--docs
|        _build
|        _static
|        _templates
|        conf.py
|        index.rst
|        make.bat
|        Makefile
|        modules.rst
|        program.rst
|    |--program
|          __init__.py
|          Camera.py
|          Database.py
|          Dataset.py
|          Detection.py
|          ...

conf.py 配置内容

import os
import sys

sys.path.insert(0, os.path.abspath('..'))


extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.viewcode',
    'sphinx.ext.napoleon'
]

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

html_theme = 'sphinx_rtd_theme'
html_static_path = []

modules.rst 内容

program
=======

.. toctree::
   :maxdepth: 4

   program

Detection.py 导入语句（前几行）

from Camera import Camera

错误信息

Sphinx可正常生成Camera文件的文档，但生成Detection模块文档时出现错误：
WARNING: autodoc: failed to import module 'Detection' from module 'program'; the following exception was raised: No module named 'Camera'

项目运行时所有类均可正常访问，仅Sphinx生成文档时出错。

问题原因与解决方法

原因

项目运行时，Python解释器的工作目录或sys.path包含了program目录，直接from Camera import Camera能找到模块。但Sphinx从docs目录启动，虽然conf.py中把Main Folder加入了sys.path，但此时Camera不是顶级模块，Python无法直接定位，必须通过包路径导入。

解决方法

有两种可行方案：

方案1：使用相对导入
修改Detection.py中的导入语句为相对导入格式，明确从当前包下导入Camera模块：
```
from .Camera import Camera
```
方案2：使用完整包路径导入
基于已配置的sys.path，直接通过完整包名导入：
```
from program.Camera import Camera
```