Sphinx AutoAPI 简介

Sphinx AutoAPI 是用于生成完整 API 文档的 Sphinx 扩展，它不需要加载、运行或导入正在记录的项目。

与传统的 Sphinx autodoc 不同，后者需要一些手动编写并使用代码导入，而 AutoAPI 通过解析源代码来查找和生成文档。

安装：

pip install sphinx-autoapi

要启用扩展，我们需要将其添加到Sphinx的conf.py文件中的扩展列表中:

extensions = ['autoapi.extension']

只需要设置必需的配置选项。autoapi_dirs 告诉 AutoAPI 哪些目录包含要记录的源代码。这些可以是绝对的，也可以是相对于文档文件的源目录的。例如，假设有一个包，已经使用 sphinx-quickstart 在 doc/ 文件夹中创建了 Sphinx 项目。目录结构可能是这样的：

mypackage/
├── docs
│   ├── _build
│   ├── conf.py
│   ├── index.rst
│   ├── make.bat
│   ├── Makefile
│   ├── _static
│   └── _templates
├── mypackage
│   ├── _client.py
│   ├── __init__.py
│   └── _server.py
└── README.md

sphinx-quickstart 将 sphinx-build 设置为从 doc/ 目录中运行，源代码在上一级。所以 autoapi_dirs 选项的值应该是：

autoapi_dirs = ['../mypackage']

如果您记录了许多包，您可以将 AutoAPI 指向包含这些包的目录。例如，如果源代码在 src/ 目录中：

mypackage/
├── docs
│   ├── _build
│   ├── conf.py
│   ├── index.rst
│   ├── make.bat
│   ├── Makefile
│   ├── _static
│   └── _templates
├── README.md
└── src
    └── mypackage
        ├── _client.py
        ├── __init__.py
        └── _server.py

autoapi_dirs 选项的值应该是：

autoapi_dirs = ['../src']

既然所有配置都已完成，当你运行 Sphinx 时，AutoAPI 将生成文档！

cd doc/
sphinx-build -b html . _build