Sphinx autodoc路径问题：分离源码与构建目录时无法导入模块

问题场景 #

场景1（正常工作） #

使用sphinx-quickstart选择不分离源码与构建目录（选'N'），目录结构如下，可成功构建HTML并识别my_project.main：

.
├── docs
│   ├── build
│   ├──_static
│   ├──_templates
│   ├──conf.py
│   └──index.rst
└── my_project
    └── main.py

场景2（无法工作） #

选择分离源码与构建目录（选'Y'），构建HTML时出现导入错误：

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

疑问解答 #

1. 如何添加向上两级的路径到sys.path？ #

文件系统不存在...这种路径标识，要指向向上两级目录，需用../..。在分离目录结构下，conf.py位于docs/source/，在该文件中添加如下代码：

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

os.path.abspath('../..')会将相对路径转换为绝对路径，直接指向包含my_project和docs的项目根目录，让Python能正确识别my_project包。

2. 其他可能遗漏的配置？ #

• 确保my_project是合法Python包：在my_project目录下创建空的__init__.py文件，Python依赖这个文件识别目录为包。
• 检查conf.py的扩展配置：确认已启用sphinx.ext.autodoc，即extensions列表包含该项：

  extensions = ['sphinx.ext.autodoc']
  

• 验证rst文件的指令正确性：确保文档文件中使用了正确的autodoc指令，比如：

  .. automodule:: my_project.main
     :members:
  

• 确认构建命令的执行位置：分离目录结构下，通常进入docs目录执行make html，或在项目根目录执行sphinx-build docs/source docs/build，保证路径对应正确。

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