从代码中自动生成文档

In the previous section of the tutorial you manually documented a Python function in Sphinx. However, the description was out of sync with the code itself, since the function signature was not the same. Besides, it would be nice to reuse Python docstrings in the documentation, rather than having to write the information in two places.

幸运的是，autodoc 插件 提供了这个功能。

用 autodoc 复用使用签名和文档串

要使用 autodoc，首先要把它添加到启用的扩展列表中：

docs/source/conf.py

extensions = [
    'sphinx.ext.duration',
    'sphinx.ext.doctest',
    'sphinx.ext.autodoc',
]

接下来，将 .. py:function 指令的内容移到原始 Python 文件中的函数文档串中，如下所示：

lumache.py

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 指令：

docs/source/usage.rst

you can use the ``lumache.get_random_ingredients()`` function:

.. autofunction:: lumache.get_random_ingredients

如果你现在建立 HTML 文档，输出将是一样的！。好处是它是由代码本身生成的。Sphinx 从文档字符串中提取了 reStructuredText 并将其包括在内，同时也生成了适当的交叉引用。

你也可以从其他对象自动生成文档。例如，为 InvalidKindError 异常添加代码：

lumache.py

class InvalidKindError(Exception):
    """Raised if the kind is invalid."""
    pass

然后用 autoexception 替换 .. py:exception 指令，如下所示：

docs/source/usage.rst

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 插件：

docs/source/conf.py

extensions = [
   'sphinx.ext.duration',
   'sphinx.ext.doctest',
   'sphinx.ext.autodoc',
   'sphinx.ext.autosummary',
]

接下来，用这些内容创建一个新的 api.rst 文件：

docs/source/api.rst

API
===

.. autosummary::
   :toctree: generated

   lumache

记住在根 toctree 中包括新的文件：

docs/source/index.rst

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 文件中。”

备注

生成的文件是基于 Jinja2 模板，该模板 可以定制，但这不属于本教程的范围。