无法按Git说明生成OpenMDAO离线文档，请求解决方案

问题1：autodoc无法导入模块警告 #

• 原因：jax_explicit_comp等属于OpenMDAO可选依赖模块，默认pip安装未包含jax相关组件
• 修复步骤：
  1. 在线环境先安装可选依赖：pip install openmdao[jax]，离线环境需提前下载对应包后本地安装
  2. 若无需这些模块的文档，修改Sphinx配置文件conf.py，添加：

     autodoc_mock_imports = ['jax', 'openmdao.components.jax_explicit_comp']
     

     把所有提示缺失的模块加入列表，跳过导入检查

问题2：Sphinx构建错误 #

错误1：myst_nb.core.variables.RetrievalError: No key 'code_src68' found in glue data #

• 原因：myst-nb版本与OpenMDAO文档构建依赖不兼容，或文档源码缺失notebook/glue数据
• 修复：
  1. 安装OpenMDAO文档指定的依赖版本：找到项目根目录的requirements-docs.txt，执行pip install -r requirements-docs.txt（需提前下载该文件及对应依赖包）
  2. 若克隆了OpenMDAO仓库，确保仓库完整，无缺失notebook文件

错误2：TypeError: _log() got an unexpected keyword argument 'line' #

• 原因：Sphinx或其依赖包版本过高，与OpenMDAO构建脚本不兼容
• 修复：
  1. 降级Sphinx到兼容版本，示例：pip install sphinx==4.5.0（具体版本以requirements-docs.txt中的指定为准）
  2. 同步所有文档依赖版本到requirements-docs.txt指定的版本

替代方案（离线学习优先推荐） #

• 提前下载官方预生成的离线HTML文档：直接解压后用浏览器打开index.html即可浏览完整内容
• 切换到OpenMDAO稳定版本分支（如3.25.0）构建文档，开发分支可能存在构建不稳定问题
• 使用预配置的Docker镜像：拉取包含OpenMDAO及预生成文档的镜像，离线运行容器后访问内部文档

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