从代码自动生成文档

在教程的 上一节 中,你手动在 Sphinx 中记录了一个 Python 函数.然而,描述与代码本身不同步,因为函数签名不一样.此外,在文档中重用 Python 文档字符串 会很好,而不是必须在两个地方写信息.

幸运的是,:doc:autodoc 扩展 </usage/extensions/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"]

最后,将 Sphinx 文档中的 .. py:function 指令替换为 autofunction:

docs/source/usage.rst
you can use the ``lumache.get_random_ingredients()`` function:

.. autofunction:: lumache.get_random_ingredients

如果你现在构建 HTML 文档,输出将是一样的!优势在于它是从代码本身生成的.Sphinx 从 docstring 中提取了 reStructuredText 并包含它,同时也生成了适当的交叉引用.

你也可以从其他对象自动生成文档.例如,添加 InvalidKindError 异常的代码:

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

并将 .. py:exception 指令替换为 autoexception 如下:

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,对应于一个新创建的 reStructuredText 文件 generated/lumache.rst,并包含模块成员的摘要,在这种情况下是一个函数和一个异常.

由 autosummary 创建的摘要页面

由 autosummary 创建的摘要页面

摘要页面中的每个链接都会带你到你最初使用相应 autodoc 指令的地方,在这种情况下是在 usage.rst 文档中.

备注

生成的文件基于 Jinja2 模板 ,这些模板 可以自定义 ,但这是本教程的范围之外.