Sphinx执行make html时缺失3个aepsych模块文档的求助

问题背景 #

执行make html生成Sphinx文档时，大部分模块文档可正常生成，但aepsych.database、aepsych.plotting、aepsych.server三个模块的文档完全缺失。此前该仓库可正常生成完整文档，近期重建时出现依赖导入警告，添加autodoc_mock_imports解决警告后，仍存在模块文档缺失问题；执行make html无报错，但卡在源码读取25%（benchmark阶段）。

环境与配置信息 #

仓库结构 #

aepsych-fork/
|__ aepsych/      # 文档目标模块目录
|__ sphinx/
|   |__ build/
|   |__ Makefile
|   |__ make.bat
|   |__ source/
|       |___conf.py
|       |___index.rst
# 其他文件

conf.py核心配置 #

import os
import sys

current_dir = os.path.dirname(__file__)
target_dir = os.path.abspath(os.path.join(current_dir, "../.."))
sys.path.insert(0, target_dir)

# 已添加的依赖mock配置
autodoc_mock_imports = ["botorch", 'gpytorch', "torch"]

已尝试操作 #

1. 添加autodoc_mock_imports解决了gpytorch等依赖的导入警告
2. 为原本为空的aepsych/database/__init__.py补充模块导出代码，但问题未解决：

import sys
from ..config import Config
from .db import Database

__all__ = ["Database"]
Config.register_module(sys.modules[__name__])

解决建议 #

1. 检查索引文件是否包含目标模块 #

确认sphinx/source/index.rst中是否显式列出这三个模块的文档生成指令，比如使用autosummary或automodule：

.. autosummary::
   :toctree: generated

   aepsych.database
   aepsych.plotting
   aepsych.server

若未添加这些条目，Sphinx会自动忽略对应模块。

2. 验证模块能否被Python正常导入 #

在项目根目录启动Python交互环境，尝试导入三个模块：

import aepsych.database
import aepsych.plotting
import aepsych.server

若导入失败，检查模块内是否有未被mock的依赖（比如plotting可能依赖matplotlib，需加入autodoc_mock_imports），或模块自身的导入逻辑是否存在问题。

3. 检查Sphinx的排除与自动发现配置 #

• 确认conf.py中exclude_patterns未排除这三个模块的源码
• 检查autodoc_default_options是否存在影响模块解析的配置

4. 清理缓存后重新构建 #

执行以下命令清理旧构建文件与缓存，再重新生成文档：

cd sphinx
make clean
make html

缓存文件可能保留旧的缺失状态，清理后可排除缓存干扰。

5. 查看Sphinx详细构建日志 #

执行构建命令时开启详细日志，获取模块解析的完整信息：

make html VERBOSE=1

从日志中可确认Sphinx是否尝试解析这三个模块，以及是否存在隐藏的跳过原因或错误。

6. 检查其他模块的__init__.py配置 #

针对plotting和server模块，确认它们的__init__.py是否正确导出内容，或是否存在未处理的导入依赖，这些都可能导致Sphinx跳过文档生成。

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