使用Sphinx生成Python包文档时无法识别run.py模块求助

1. 确认源码路径已加入Python搜索路径 #

Sphinx必须能定位到你的模块所在目录，检查conf.py中是否将src目录添加到sys.path：

import os
import sys
# 根据conf.py的实际位置调整路径，比如conf.py在docs/source下则用../../src
sys.path.insert(0, os.path.abspath('../src'))

路径错误会直接导致Sphinx找不到目标模块。

2. 检查包结构合法性 #

Python要求目录包含__init__.py才会被识别为可导入的包。确认src/vr_format_conversion/format_conversion/下存在__init__.py文件（空文件即可），若缺失则立即创建。

3. 修正rst文件中的模块引用 #

使用autodoc扩展时，模块路径需从根包开始完整书写，禁止使用相对路径：

.. automodule:: vr_format_conversion.format_conversion.run
   :members:
   :undoc-members:
   :show-inheritance:

模块名拼写错误或层级缺失都会导致Sphinx无法识别。

4. 清理Sphinx构建缓存 #

旧缓存可能掩盖模块更新，执行以下命令清理后重新构建：

make clean
make html

5. 验证必要扩展已启用 #

确保conf.py的extensions列表中包含sphinx.ext.autodoc：

extensions = [
    'sphinx.ext.autodoc',
    # 其他你需要的扩展
]

未启用autodoc则无法自动生成模块文档。

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