从代码自动生成文档¶
在上一节教程中，您在 Sphinx 中手动记录了一个 Python 函数。但是，描述与代码本身不一致，因为函数签名不同。此外，将Python 文档字符串重用于文档中会很好，而不是不得不将信息编写到两个地方。
幸运的是，autodoc 扩展提供了此功能。
使用 autodoc 重用签名和文档字符串¶
要使用 autodoc，首先将其添加到已启用扩展的列表中
extensions = [
'sphinx.ext.duration',
'sphinx.ext.doctest',
'sphinx.ext.autodoc',
]
接下来，将 .. py:function 指令的内容移到原始 Python 文件中的函数文档字符串中，如下所示
def get_random_ingredients(kind=None):
"""
Return a list of random ingredients as strings.
:param kind: Optional "kind" of ingredients.
:type kind: list[str] or None
:raise lumache.InvalidKindError: If the kind is invalid.
:return: The ingredients list.
:rtype: list[str]
"""
return ["shells", "gorgonzola", "parsley"]
最后，用autofunction替换 Sphinx 文档中的 .. py:function 指令
you can use the ``lumache.get_random_ingredients()`` function:
.. autofunction:: lumache.get_random_ingredients
如果您现在构建 HTML 文档，输出将相同！它从代码本身生成，具有优势。Sphinx 从文档字符串中获取了 reStructuredText 并将其包含在内，也生成了正确的交叉引用。
您还可以从其他对象自动生成文档。例如，添加 InvalidKindError 异常的代码
class InvalidKindError(Exception):
"""Raised if the kind is invalid."""
pass
并将 .. py:exception 指令替换为autoexception，如下所示
or ``"veggies"``. Otherwise, :py:func:`lumache.get_random_ingredients`
will raise an exception.
.. autoexception:: lumache.InvalidKindError
同样，在运行 make html 之后，输出将与之前相同。
生成完整的 API 参考¶
虽然使用 sphinx.ext.autodoc 使代码和文档保持同步变得容易得多，但您仍然需要为每个要记录的对象编写一个 auto* 指令。Sphinx 提供了另一级别的自动化：autosummary 扩展。
autosummary 指令生成包含所有必要 autodoc 指令的文档。要使用它，首先启用 autosummary 扩展
extensions = [
'sphinx.ext.duration',
'sphinx.ext.doctest',
'sphinx.ext.autodoc',
'sphinx.ext.autosummary',
]
接下来，创建一个新的 api.rst 文件，其内容如下
API
===
.. autosummary::
:toctree: generated
lumache
记住将新文档包含在根 toctree 中
Contents
--------
.. toctree::
usage
api
最后，在运行 make html 构建 HTML 文档后，它将包含两个新页面
api.html，对应于docs/source/api.rst，并包含一个包含您在autosummary指令中包含的对象的表格（在本例中只有一个）。generated/lumache.html，对应于新创建的 reStructuredText 文件generated/lumache.rst，并包含模块成员的摘要，在本例中为一个函数和一个异常。
由 autosummary 创建的摘要页面¶
摘要页面中的每个链接都将带您到您最初使用相应 autodoc 指令的地方，在本例中为 usage.rst 文档。