Sphinx Auto-API相对导入层级过多报错求助

首次提问，若有信息遗漏请见谅。用sphinx-auto-api生成文档，之前项目运行正常，但现在某个site-packages里的导入语句触发报错。

执行命令 #

sphinx-build -b dummy docs docs/_build/html --keep-going 

conf.py 配置内容 #

import os
import sys

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

运行环境 #

在Poetry环境中执行上述命令。

报错信息 #

[AutoAPI] Reading files... [ 11%] /Users/marta/PycharmProjects/app/app/lib/python3.10/site-packages/requests-stubs/api.pyi                                                                           
Extension error (autoapi.extension):
Handler <function run_autoapi at 0x107c7da20> for event 'builder-inited' threw an exception (exception: Relative import with too many levels (1) for module 'api')

相关包版本 #

Sphinx = "^6.1.0"
sphinx-rtd-theme = "^2.0.0"
sphinx-pydantic = "^0.1.1"
sphinx-autoapi = "^3.0.0"

这个问题是因为sphinx-auto-api默认会扫描所有能找到的Python文件，包括site-packages里的requests-stubs/api.pyi，而这个文件里的相对导入在当前扫描上下文里不合法，导致报错。

可以用以下两种方法解决：

1. 指定AutoAPI只扫描你的项目代码
   在conf.py里添加autoapi_dirs配置，明确指向你自己的项目代码目录，避免扫描无关的site-packages文件：

autoapi_dirs = ['../your_project_code']  # 替换成你实际的项目代码文件夹路径

2. 直接排除site-packages目录
   如果不想指定具体扫描目录，也可以配置autoapi_ignore来排除所有site-packages路径：

autoapi_ignore = ['*/site-packages/*']

另外，你的sys.path配置把项目根目录加到了最前面，这可能让AutoAPI误扫到site-packages里的文件，确保autoapi的扫描范围只限定在你的项目代码里即可。

内容的提问来源于stack exchange，提问作者Marta P.