操作指南¶
这些指南将引导您完成在AutoAPI中执行常见操作或解决常见问题的步骤。它们假设您已经有设置了AutoAPI的Sphinx项目。如果您不知道如何做到这一点，请阅读 教程。
如何自定义要记录的内容¶
使用默认设置时，AutoAPI 会记录在 Python 中加载时通过实际包公开访问的所有内容。例如，如果函数从子模块导入到包中，那么该函数将在子模块和包中都被记录。
备注
例外情况是，任何导入到模块中的对象默认情况下都不会被记录。
然而，有多种选项可用于控制 AutoAPI 将记录什么内容。
Set __all__¶
AutoAPI 将 __all__ 的定义（参见 Python 官方文档关于从包中导入的部分）视为模块或包中哪些对象是公开的、哪些不是的规范。
在下面的示例中，只有 func_a() 和 A 会被记录。
# mypackage/__init__.py
from . import B
__all__ = ("A", "func_a")
class A:
...
def func_a():
...
def func_b():
...
配置 autoapi_options¶
autoapi_options 配置值提供了一些对文档内容的高层次控制。
例如，您可以从 autoapi_options 中删除 private-members 并隐藏私有模块中的对象定义。
# package/__init__.py
from ._submodule import public_function
# package/_submodule.py
def public_function():
"""This public function will be documented only in ``package``."""
...
def private_function()
"""This private function won't be documented."""
...
例如，您可以从 autoapi_options 中删除 undoc-members 并只为您想要记录的模块和其他实体添加文档字符串。
配置选项的详细信息，请参阅 autoapi_options。
连接到 autoapi-skip-member 事件¶
每当模板决定是否将成员包含在文档中时，都会发出 autoapi-skip-member 事件。
例如，要仅记录包 -- 换句话说，不记录子模块 -- 您可以在 conf.py 中实现事件处理程序，如下所示。
def skip_submodules(app, what, name, obj, skip, options):
if what == "module":
skip = True
return skip
def setup(sphinx):
sphinx.connect("autoapi-skip-member", skip_submodules)
定制 API 文档模板¶
最后，您可以通过自定义模板来配置渲染的内容。这是一种较为强硬的方法，因此只有在其他选项无法满足您的控制需求时才需要使用。您可以在下一节中学习如何自定义模板：如何通过模板自定义布局。
如何通过模板自定义布局¶
警告
模板控制了很多行为，因此自定义模板可能意味着您在更新自定义模板后失去了新功能，直到您使用与 AutoAPI 新版本对应的模板为止。
您可以通过更改 AutoAPI 使用的 Jinja2 模板来自定义文档的外观。默认情况下，这些模板位于 AutoAPI 包中的 autoapi/templates 目录中。只需将您要自定义的模板复制到本地目录并进行编辑即可。要让 AutoAPI 使用这些模板，请将 autoapi_template_dir 配置选项指向您的目录。它可以是绝对的，也可以是相对于文档源目录（即传递给 sphinx-build 的目录）的相对路径。
autoapi_template_dir = '_autoapi_templates'
要覆盖 Python 类和模块模板，请将它们复制到本地目录并进行编辑。例如，要覆盖 Python 类和模块模板：
_autoapi_templates
└── python
├── class.rst
└── module.rst
如何自定义索引页面¶
AutoAPI 创建的索引页面是使用模板生成的。因此，自定义索引页面的步骤与自定义模板相同。只需按照与 自定义模板 相同的步骤编辑 autoapi/templates/index.rst 模板即可。
如何删除索引页面¶
要完全删除索引页面，请关闭 autoapi_add_toctree_entry 配置选项:
autoapi_add_toctree_entry = False
您将需要在 toctree 中包含生成的文档。例如，如果您正在为名为“example”的包生成文档，您将添加以下 toctree 条目:
.. toctree::
autoapi/example/index
注意，autoapi/ 是默认的文档输出位置，由 autoapi_root 配置选项定义。如果您更改 autoapi_root，则需要添加的条目也会更改。
如何配置文档在 TOC 树中的位置¶
配置选项 autoapi_root 定义了生成文档的输出位置。要更改文档的位置，只需将此选项更改为相对于文档源目录的另一个目录：
autoapi_root = 'technical/api'
如何过渡到 Autodoc 风格的文档¶
一旦您已经使用 Autodoc 风格指令 编写了一些文档，将自动文档生成关闭就很简单了。只需禁用 autoapi_generate_api_docs 配置选项即可：
autoapi_generate_api_docs = False
如何过渡到手动文档¶
要从 AutoAPI 生成的文件开始编写自己的 API 文档，您可以使用 autoapi_keep_files 配置选项将其生成的文件保留为基础来开始:
autoapi_keep_files = True
一旦您使用此选项打开了文档的构建，您就可以从您的项目中完全禁用 AutoAPI。
如何将类型注释作为类型在渲染的文档字符串中显示¶
警告
此功能是实验性的，未来可能会更改或移除。
从 v3.0 开始，sphinx 包括了一个 sphinx.ext.autodoc.typehints 扩展，它能够将类型注释作为参数类型和返回类型进行渲染。
例如以下函数：
def _func(a: int, b: Optional[str]) -> bool
"""My function.
:param a: The first arg.
:param b: The second arg.
:returns: Something.
"""
会被渲染为：
- _func(a, b)
AutoAPI 能够执行相同的操作。要启用此行为，请在 Sphinx 的 conf.py 文件中加载 sphinx.ext.autodoc.typehints （或 sphinx.ext.autodoc）扩展，并将 autodoc_typehints 设置为 description 正常:
extensions = ['sphinx.ext.autodoc', 'autoapi.extension']
autodoc_typehints = 'description'
备注
除非 autodoc_typehints 设置为 None，否则重载的类型注释将始终在签名中输出，并且不会合并到描述中，因为无法将所有重载表示为参数列表。