Sphinx构建Greengrass V2文档时的语义版本控制问题

问题根源 #

你的场景中，com.example是带点的文件夹名称而非Python包结构，但Sphinx的autodoc模块会默认将路径中的点解析为Python模块层级分隔符，导致它尝试从不存在的com模块导入子模块，最终抛出No module named 'com'的错误。

解决方案 #

1. 调整Python路径（在conf.py中配置） #

在文档目录的conf.py文件中，将com.example文件夹的路径添加到Python的sys.path中，让Python能直接识别该文件夹下的子目录和模块，而非将com.example解析为包层级：

import os
import sys
# 将com.example文件夹的绝对路径加入sys.path
sys.path.insert(0, os.path.abspath('../com.example'))

2. 正确引用模块 #

根据1.0.0目录是否为Python包，选择对应的引用方式：

• 如果1.0.0包含__init__.py（属于Python包），在.rst文档中这样引用：

  .. automodule:: 1.0.0.test
     :members:
  

• 如果1.0.0无__init__.py（不属于Python包），则需要把1.0.0的路径也加入sys.path：

  # 在conf.py中追加配置
  sys.path.insert(0, os.path.abspath('../com.example/1.0.0'))
  

  然后在.rst中直接引用模块：

  .. automodule:: test
     :members:
  

3. 替代方案：使用mock导入（仅适用于无需执行模块代码的场景） #

如果模块导入依赖复杂，且不需要实际执行代码生成文档，可以在conf.py中添加mock配置，跳过真实模块的导入：

autodoc_mock_imports = ['com']

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