从代码中自动生成文档¶
在 前一节 的教程中，你在 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
然后用 autoexception 替换 .. py:exception 指令，如下所示：
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，对应于新创建的 reST 文件generated/lumache.rst，包含模块成员的摘要，在这种情况下是一个函数和一个异常。
由 autosummary 创建的摘要页面¶
摘要页中的每个链接将带你到你最初使用相应的 autodoc 指令的地方，在这种情况下是在 usage.rst 文件中。”