为什么sphinx-autoapi生成的API参考页面为空，无对应模块链接？

你的问题核心来自日志里明确给出的两个警告：AutoAPI生成的文档页面没有被加入Sphinx的全局目录树（toctree），因此主页面不会展示API参考的入口链接。另外你看不到日志里提及的rst文件属于正常现象，AutoAPI默认会把生成的rst存放在构建缓存目录，不会写入你的docs源目录，不属于配置错误。

• 把AutoAPI入口加入主文档目录树 #

打开你docs目录下的index.rst文件，在toctree配置块中添加autoapi/index条目，示例配置如下：

.. toctree::
   :maxdepth: 2
   :caption: API参考
   
   autoapi/index

如果你的toctree已有其他页面条目，直接追加这一行即可。

• 删除冗余冲突配置 #

你的conf.py中同时配置了互斥的autoapi_modules和autoapi_dirs参数，前者用于手动指定要解析的模块，后者用于自动扫描指定目录下的所有模块，同时配置会导致逻辑冲突，直接删除autoapi_modules = {'testdoc.lib.a': {}}这行即可。

• （可选）持久化AutoAPI生成的源文件 #

如果你希望自定义生成的API文档，可以在conf.py中添加以下配置，让AutoAPI把生成的rst文件持久化到你的docs源目录下：

autoapi_keep_files = True

设置后构建时会在docs/autoapi目录下生成对应的rst文件，你可以直接修改这些文件调整展示内容。

执行以下命令清理旧构建缓存并重新生成文档：

make clean html

构建完成后打开首页即可看到API参考的入口，点击即可进入生成的模块文档，原来的两个toctree警告也会消失。

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