使用Sphinx及autodoc导入Python模块文档字符串时模块无法被检测的问题解决

针对你遇到的No module named 'Modules'警告，我整理了几个常见的排查和解决方向，你可以按顺序尝试：

1. 给模块目录添加__init__.py文件 #

Sphinx的autodoc依赖Python的包导入机制，即便Python 3.3+支持无__init__.py的命名空间包，但autodoc对这类包的识别经常出问题。你需要在Module_1和Module_2目录下各创建一个空的__init__.py文件，让Python把它们识别为可导入的包：

Modules:
|------ Module_1
|-------- __init__.py  # 新增空文件
|-------- 你的脚本文件.py
|------ Module_2
|-------- __init__.py  # 新增空文件
|-------- 你的脚本文件.py

2. 修正conf.py中的路径配置 #

你当前的路径写法依赖执行命令时的工作目录，容易出问题。换成基于conf.py自身位置的绝对路径拼接，更可靠：
打开Documentation/source/conf.py，替换原有的路径代码为：

import os
import sys
# 获取当前conf.py所在目录的绝对路径
source_root = os.path.dirname(os.path.abspath(__file__))
# 向上两级找到Main_Folder，再拼接Modules目录
modules_path = os.path.join(source_root, '../../Modules')
sys.path.insert(0, os.path.abspath(modules_path))

# 可选：添加打印验证路径是否正确，执行sphinx-build时会输出
print(f"Added Modules path to sys.path: {os.path.abspath(modules_path)}")

3. 确认rst文件中的模块名与实际匹配 #

你在Module_1.rst里写的是.. automodule:: Module_1，这要求Module_1是一个可直接导入的模块。如果你的核心代码在Module_1目录下的某个脚本里（比如core.py），那需要调整rst内容：

Module_1
===========
.. automodule:: Module_1.core
    :members:

或者在Module_1/__init__.py里导入脚本内容，比如：

from .core import *

这样import Module_1就能正确加载你要生成文档的代码。

4. 验证虚拟环境与执行环境 #

确保你激活的是项目根目录下的.venv_folder虚拟环境，并且Sphinx是安装在这个环境里的。有时候误用到系统Python会导致路径和依赖不匹配，引发导入错误。

完成以上步骤后，回到Documentation目录，重新执行：

sphinx-build -b html source build

如果还是有问题，可以查看sphinx-build的输出日志，看看我们添加的打印是否显示了正确的Modules路径，或者有没有更详细的导入错误信息，再针对性调整。

内容的提问来源于stack exchange，提问作者An old man in the sea.