本地构建文档时Autosummary无法导入包类方法的问题

项目背景 #

我正在通过simple-stimuli沙箱项目学习文档构建，CI（配置位于项目根目录下.github/workflows/doc.yml）构建的文档无警告且HTML显示正常，但本地构建（曾正常，现异常）出现问题。

问题现象 #

本地构建时出现46条类似以下的警告，无法自动生成包内类的方法文档：

C:\Users\Mathieu\Documents\git\mscheltienne\simple-stimuli\stimuli\visuals\text.py:docstring of stimuli.visuals.text.Text:38: WARNING: autosummary: failed to import putText.
Possible hints:
* ModuleNotFoundError: No module named 'stimuli.visuals.Text.putText'; 'stimuli.visuals.Text' is not a package
* ValueError: not enough values to unpack (expected 2, got 1)
* ModuleNotFoundError: No module named 'stimuli.visuals.putText'
* ModuleNotFoundError: No module named 'putText'
* KeyError: 'putText'
* AttributeError: module 'stimuli.visuals.Text' has no attribute 'putText'
* AttributeError: module 'stimuli.visuals' has no attribute 'putText'
C:\Users\Mathieu\Documents\git\mscheltienne\simple-stimuli\stimuli\visuals\text.py:docstring of stimuli.visuals.text.Text:38: WARNING: autosummary: failed to import show.
Possible hints:
* KeyError: 'show'
* AttributeError: module 'stimuli.visuals.Text' has no attribute 'show'
* ModuleNotFoundError: No module named 'stimuli.visuals.show'
* ModuleNotFoundError: No module named 'stimuli.visuals.Text.show'; 'stimuli.visuals.Text' is not a package
* ValueError: not enough values to unpack (expected 2, got 1)
* AttributeError: module 'stimuli.visuals' has no attribute 'show'
* ModuleNotFoundError: No module named 'show'

最初问题出在本地检出gh-pages分支（非Python包）且环境为可编辑安装后，但重新克隆项目并在全新虚拟环境中安装仍无法解决。

复现步骤 #

git clone simple-stimuli项目仓库

python3 -m venv test --copies
# macOS/Linux激活环境
source test/bin/activate
# Windows激活环境
test/Scripts/activate.bat
pip install --upgrade pip setuptools wheel

cd simple-stimuli
pip install -e .[all]
cd doc
make html

尝试使用CI的构建命令（已调整路径）：

sphinx-build ./main/doc ./doc-build/dev -W --keep-going

结果一致，仍出现相同警告。

环境差异 #

该问题在macOS和Windows本地环境均出现，但Linux环境（与CI使用的ubuntu-latest一致）构建正常。

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