如何修复仅在Read the Docs上出现的autoapi.not_readable错误？

1. 锁定依赖版本，规避环境差异 #

• 查看本地构建环境中sphinx、sphinx-autoapi的具体版本，在项目根目录创建requirements-docs.txt文件，写入对应版本号，比如：

  sphinx==4.5.0
  sphinx-autoapi==1.9.0
  

• 进入Read the Docs项目设置页面，找到"Advanced Settings"，将"Requirements file"设置为requirements-docs.txt，强制构建环境使用和本地一致的依赖版本。

2. 修正AutoAPI路径配置 #

• 打开文档配置文件conf.py，检查autoapi_dirs的路径定义，避免相对路径在RTD环境下解析错误，改用绝对路径：

  import os
  # 替换成你的包所在的相对路径
  autoapi_dirs = [os.path.abspath("../your_package")]
  

• 同时检查autoapi_ignore配置，确认没有误将整个包目录加入忽略列表。

3. 调整RTD构建的项目安装设置 #

• 在RTD项目设置的"Advanced Settings"中，开启"Install project"选项，确保构建环境会将你的包安装到site-packages目录，AutoAPI可以正常读取已安装的包文件。
• 如果项目包含子模块，在设置中开启"Clone submodules"选项，避免源码缺失导致无法读取。

4. 适配AutoAPI命名空间配置 #

• 在conf.py中添加以下配置，解决命名空间包的读取问题：

  autoapi_python_use_implicit_namespaces = True
  

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