如何使用Sphinx为Blender Python代码生成文档？

这个问题我之前帮不少开发者处理过，核心原因很明确：bpy是Blender内置的专属Python模块，只有在Blender自带的Python环境里才能正常导入，而Sphinx默认用的是系统或虚拟环境里的普通Python，自然找不到它。下面给你三个靠谱的解决办法，按推荐程度排序：

1. 使用Sphinx的Mock模拟模块（最简便） #

这是Sphinx官方推荐的处理缺失依赖的方案，原理是让Sphinx创建一个模拟的bpy模块结构，不用真的导入就能解析代码里的相关引用。

步骤很简单：

• 打开你的Sphinx配置文件conf.py
• 添加或修改autodoc_mock_imports配置项，把所有Blender相关的模块都加进去：

  autodoc_mock_imports = ['bpy', 'bpy.types', 'bpy.data', 'bpy.context']
  

• 保存后重新运行cd doc/ && make html，就能正常生成文档了。

这个方法适合大多数场景，尤其是你的代码里只是导入bpy并调用基础API的情况，完全不需要改动代码或环境。

2. 让Sphinx使用Blender自带的Python环境运行（最准确） #

如果你的文档需要真实解析bpy的API细节（比如要生成bpy.data.objects的具体类型说明），可以让Sphinx直接在Blender的Python环境里执行。

步骤如下：

1. 找到Blender安装路径下的Python解释器：
   • Windows：一般在C:\Program Files\Blender Foundation\Blender X.X\X.X\python\bin\python.exe（X.X是Blender版本号）
   • Linux：比如/usr/bin/blender-X.X/X.X/python/bin/python3
   • macOS：/Applications/Blender.app/Contents/Resources/X.X/python/bin/python3
2. 用这个Python解释器安装Sphinx：

   # 以Windows为例
   "C:\Program Files\Blender Foundation\Blender 3.6\3.6\python\bin\python.exe" -m pip install sphinx
   

3. 用Blender的Python运行Sphinx生成文档：

   # Windows
   "C:\Program Files\Blender Foundation\Blender 3.6\3.6\python\bin\python.exe" -m sphinx-build doc/source doc/build/html
   # Linux/macOS
   /path/to/blender/python/bin/python3 -m sphinx-build doc/source doc/build/html
   

这种方式能完全模拟Blender的运行环境，生成的文档对bpy相关API的解析会更准确，但需要额外配置环境，适合对文档精度要求高的场景。

3. 手动创建假的bpy模块（最麻烦，不推荐） #

如果上面两种方法都不适用，你可以手动在项目根目录创建一个假的bpy模块结构，让Sphinx能识别它。比如：

• 项目根目录下新建bpy文件夹，里面创建__init__.py
• 在bpy文件夹里再新建data子文件夹，创建__init__.py，并在里面定义一个空的Objects类：

  # bpy/data/__init__.py
  class Objects:
      pass
  

• 类似地，根据你代码里用到的bpy子模块，补充对应的假结构。

这个方法需要手动维护假模块的结构，一旦代码里用到新的bpyAPI，就要更新假模块，非常繁琐，除非有特殊需求，否则不建议使用。

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