教程

这些教程将指导您开始使用 AutoAPI。它们假设您已经设置了基本的 Sphinx 项目。如果您不确定如何操作，可以查看 Sphinx 文档中的 Getting started 指南。

设置自动 API 文档生成

安装 AutoAPI 的推荐方法是通过 virtualenv。一旦您设置了 virtualenv，您可以使用以下命令安装 AutoAPI：

pip install sphinx-autoapi

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

extensions = ['autoapi.extension']

只需要设置必需的配置选项。autoapi_dirs 告诉 AutoAPI 哪些目录包含要记录的源代码。这些路径可以是绝对路径，也可以是相对于文档文件源目录的相对路径。例如，假设我们有一个包，并且使用 sphinx-quickstart 在 docs/ 文件夹中创建了 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 设置为从 docs/ 目录运行，源代码位于上一级目录。因此我们的 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 docs/
sphinx-build -b html . _build

成功生成文档后，你应该能够打开 _build/index.html 文件并在浏览器中查看。页面上将有目录链接到由 AutoAPI 生成的 API 参考文档。

下一个，你可能想了解如何 自定义要记录的内容 或 自定义或删除 API 参考索引页面。