使用autodoc_mock_imports后仍遇Sphinx 'No module named'异常

问题根源 #

报错来自sphinx_automodapi.automodsumm扩展在builder-inited事件阶段的提前模块导入，而autodoc_mock_imports的Mock逻辑要到后续文档生成阶段才会生效，导致依赖缺失的错误被提前触发，常规Mock配置无法覆盖这个场景。

可行解决方案 #

方案1：手动提前Mock依赖 #

在conf.py最开头添加手动Mock代码，在Sphinx加载任何扩展前就替换缺失的依赖：

import sys
from unittest.mock import Mock

# Mock pandas及其他无法安装的依赖
sys.modules['pandas'] = Mock()
# 若需Mock子模块（如pandas.DataFrame），可补充：
# sys.modules['pandas'].DataFrame = Mock()

方案2：调整配置顺序并控制autosummary生成时机 #

1. 把autodoc_mock_imports放在extensions配置之前，同时关闭自动生成autosummary：

   autodoc_mock_imports = ['pandas']
   autosummary_generate = False
   
   extensions = [
       'sphinx.ext.autodoc',
       'sphinx.ext.imgmath',
       'sphinx.ext.napoleon',
       'sphinx.ext.intersphinx',
       'sphinx.ext.autosummary',
       'sphinx_automodapi.automodapi'
   ]
   

2. 若需要autosummary内容，先手动生成对应的文件，再执行make html，避免扩展在早期自动导入模块。

方案3：检查Mock名称匹配性 #

确保autodoc_mock_imports的名称与代码中的导入方式完全一致：

• 代码中是import pandas或from pandas import xxx，则['pandas']正确；
• 代码中直接导入子模块（如import pandas.core），则需补充子模块到Mock列表：['pandas', 'pandas.core']

额外验证步骤 #

• 执行make clean清空build目录后重新运行make html，避免缓存干扰；
• 确认../../src已加入sys.path，保证project.problem模块能被正确识别（虽非当前报错原因，但为文档生成基础）。

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