如何在部分嵌套目录无Python文件时使用Sphinx生成项目文档

主问题：Sphinx提示找不到faulty_meters_study模块 #

核心错误原因是你在conf.py中插入的路径层级不对：
你当前的路径配置是sys.path.insert(0, os.path.abspath('..'))，如果在docs目录下执行构建命令，该路径指向的是faulty_meters_study目录本身。但Python导入包时，需要在sys.path中加入包的父目录，才能搜索到名为faulty_meters_study的包。

修改方案很简单，把conf.py中的路径插入语句修改为：

sys.path.insert(0, os.path.abspath('../..'))

如果修改后还是报错，可以做以下验证：

• 确认你执行sphinx-apidoc、make html命令时的工作目录确实是docs目录，相对路径是基于工作目录计算的，工作目录不对会导致路径解析错误
• 可以在conf.py中临时加一行print(sys.path)，运行make html时查看输出的路径列表，确认是否包含faulty_meters_study的父目录
• 检查sphinx-apidoc生成的faulty_meters_study.rst文件，确认里面引用的模块路径没有拼写错误

附加问题：顶层可执行代码是否影响文档生成 #

分两种情况：

• 你示例中的纯运算类无副作用代码，执行时不会抛出错误，完全不会影响文档生成。默认配置下autodoc不会将未文档化的顶层变量加入生成的文档中，只会提取你写了文档字符串的函数、类等内容。
• 如果顶层代码包含读文件、连数据库、请求接口等可能报错的逻辑，导入模块时触发报错的话，会导致autodoc无法导入模块，进而无法生成文档。这种情况可以将可执行逻辑包在if __name__ == "__main__":判断中，避免导入时执行。

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