本地可构建GemGIS API参考但RTD出现导入错误，寻求解决方案

• 尝试用autosummary为Python包GemGIS构建API参考，本地构建正常，但在Read the Docs（RTD）上构建时触发ImportError和ModuleNotFoundError，提示多个GemGIS子模块（如gemgis.raster、gemgis.vector）缺失
• 核心报错信息：

  WARNING: [autosummary] failed to import gemgis.raster.calculate_aspect.
  Possible hints:

  • KeyError: 'gemgis'
  • ModuleNotFoundError: No module named 'gemgis.vector'; 'gemgis' is not a package
  • ImportError: no module named gemgis.raster

• 现有配置：conf.py本地运行正常，RTD使用的environment_dev.yml已包含GemGIS所有依赖（含可选依赖）；使用autodoc_mock_imports = ["gemgis"]可完成autosummary构建，但无法生成各方法的HTML文档
• 已尝试无效步骤：本地验证后推送GitHub、向environment_dev.yml添加可选依赖、在conf.py中添加模块路径、在文档中排除gemgis

方案1：确保RTD正确安装GemGIS包 #

RTD默认仅安装依赖清单中的第三方库，不会自动安装GemGIS包本身，需明确添加安装步骤：

• 在environment_dev.yml的pip节点下添加GemGIS的安装指令，例如从GitHub仓库安装：

  pip:
    - git+https://github.com/你的用户名/GemGIS.git@main  # 替换为实际仓库地址和分支
  

• 若GemGIS包与docs目录同级，可使用本地可编辑安装：

  pip:
    - e ../
  

方案2：精细化配置autodoc_mock_imports #

不要直接mock整个GemGIS包，而是mock导致导入失败的第三方依赖，让GemGIS本身能被正常导入：

1. 从RTD构建日志的报错信息中，提取GemGIS导入时依赖的未安装库
2. 在conf.py中仅mock这些依赖库：

   autodoc_mock_imports = ["gdal", "shapely", "pyproj"]  # 替换为实际缺失的依赖
   

3. 此方式可保留autosummary对GemGIS模块的解析能力，正常生成方法的HTML文档

方案3：修正conf.py中的路径配置 #

确保RTD构建环境能找到GemGIS包的路径：

import os
import sys
# 将GemGIS包所在目录添加到Python路径（假设包在docs的上级目录）
sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '../')))

同时确认GemGIS包结构合规：根目录存在__init__.py，子模块（如raster、vector）也包含必要的__init__.py文件，且主包__init__.py中正确导入子模块。

方案4：启用RTD的项目安装选项 #

在RTD项目的设置页面中，找到Install your project选项，选择pip install .或pip install -e .，强制RTD在构建文档前安装你的GemGIS包。

1. 提交修改后，手动触发RTD构建
2. 查看构建日志，确认GemGIS包已被正确安装，无导入错误
3. 检查生成的文档是否包含各方法的HTML页面

内容的提问来源于stack exchange，提问作者Alexander Jüstel