58

我很快就开始了一个开源 Python 项目，我正在尝试提前决定如何编写我的文档字符串。显而易见的答案是使用 reStructuredText 和 Sphinx with autodoc，因为我真的很喜欢在我的文档字符串中正确记录我的代码然后让 Sphinx 自动为我构建一个 API 文档的想法。

问题在于它使用的 reStructuredText 语法——我认为它在渲染之前完全不可读。例如：

:param path: The path of the file to wrap
:type path: str
:param field_storage: The :class:`FileStorage` instance to wrap
:type field_storage: FileStorage
:param temporary: Whether or not to delete the file when the File instance
    is destructed
:type temporary: bool

您必须真正放慢速度并花一点时间从语法混乱中弄清楚。我更喜欢 Google 的方式（Google Python Style Guide），上面的对应物是这样的：

参数：
    path (str): 要包装的文件的路径
    field_storage (FileStorage)：要包装的 FileStorage 实例
    temporary(bool): File 时是否删除文件
        实例被破坏

好多了！但当然，Sphinx 将没有这些，而是​​将所有文本呈现Args:在一行之后。

所以总结一下 - 在我去使用这种 reStructuredText 语法污染我的代码库之前，我想知道是否有任何真正的替代方法可以使用它和 Sphinx，而不仅仅是编写我自己的 API 文档。例如，是否有处理 Google Style Guide 的文档字符串样式的 Sphinx 扩展？

4

7 回答 7

75

我创建了一个Sphinx 扩展，它解析 Google 样式和 NumPy 样式的文档字符串，并将它们转换为标准的 reStructuredText。

要使用它，只需安装它：

$ pip install sphinxcontrib-napoleon

并在 conf.py 中启用它：

# conf.py

# Add autodoc and napoleon to the extensions list
extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.napoleon']

更多关于拿破仑的文档在这里。

于 2013-07-18T18:55:14.560 回答
32

我认为目前没有比sphinx记录 python 项目更好的方法了。

为了获得更清晰的文档字符串，我最喜欢的选择是sphinx与numpydoc. 根据您的示例，这看起来像：

def foo(path, field_storage, temporary):
    """This is function foo

    Parameters
    ----------
    path : str
        The path of the file to wrap
    field_storage : :class:`FileStorage`
        The :class:`FileStorage` instance to wrap
    temporary : bool
        Whether or not to delete the file when the File instance
        is destructed

    Returns
    -------
    describe : type
        Explanation
    ...

    Examples
    --------
    These are written in doctest format, and should illustrate how to
    use the function.

    >>> a=[1,2,3]
    >>> print [x + 3 for x in a]
    [4, 5, 6]
    ...
    """

    pass

（一个完整的例子是Here），HTML输出看起来像这样

我认为 rst-file 的结构更清晰，更具可读性。该指南提供了更多信息和约定。该numpydoc扩展程序也适用autodoc。

于 2012-06-24T09:14:25.423 回答
10

我使用epydoc而不是 sphinx，所以这个答案可能不适用。

您描述的用于记录方法和函数的 reStructuredText 语法并不是唯一可能的语法。到目前为止，我更喜欢使用统一的定义列表来描述参数，这与 Google 的方式非常相似：

:Parameters:
  path : str
     The path of the file to wrap
  field_storage: FileStorage
     The FileStorage instance to wrap
  temporary: bool
     Whether or not to delete the file when the File instance is destructed

如果 sphix 支持它，我会尝试。如果不是，您也可以考虑为此使用 epydoc（尽管它现在还没有积极维护）。

于 2012-06-23T09:32:56.183 回答
7

实际上，reStructuredText以及来自PEP8的样式指南主要适用于对 Python 的标准库本身进行编码，尽管许多第三方程序员也遵循这一点。

我同意你的观点，从代码的角度来看，谷歌的参数风格要好得多。但是您应该也可以使用 sphinx 生成这样的文档字符串，并保留新行和缩进。不过，它的输出不如sphinxy 格式好。

反正你不用sphinx，顺便说一下，autodocsphinx的模块肯定只是其中的一小部分。您几乎可以使用任何能够检索文档字符串内容的文档生成器，例如Epydoc（支持epytext以及reStructuredText、Javadoc 或 Plaintext）或pydoctor，甚至是更通用的文档生成器，例如Doxygen。

但可以肯定的是，sphinx 非常Python 化，与 Python 一起使用非常方便，并使您的代码与 Python 的生态系统保持一致。我认为您不是唯一一个认为这是“缺乏”的人。也许他们将来会考虑这些抱怨，或者也许你甚至可以考虑autodoc自己修改模块，应该不是很难，在 Python 中，这将是一个很好的练习。

于 2012-06-23T08:29:29.047 回答
3

你可以用你喜欢的任何格式编写文档字符串。但是，为了所有其他 Python 程序员，最好使用他们已经知道的标记和工具。如果您坚持使用 reST 和 Sphinx，他们的生活会更轻松。

于 2012-06-23T08:29:40.397 回答
2

Python 将文档字符串的内容作为__doc__附加到函数/类/变量对象的属性提供。

因此，您可以轻松编写一个 Python 程序，将文档从您喜欢的任何格式转换为您喜欢的任何格式。您甚至可以使用 Javadoc 样式、XML 或其他任何东西。

顺便说一句，由于 Sphinx 是用 Python 编写的，所以让它接受非 RST 输入只是编写少量 Python 代码的问题。

于 2012-06-23T07:26:42.810 回答
0

您只需要开始一个新行并在每个变量名称后添加一个水龙头。然后用连续的粗体变量名在几行中呈现：

Args:
    path (str):
        The path of the file to wrap
    field_storage (FileStorage):
        The FileStorage instance to wrap
    temporary (bool):
        Whether or not to delete the file when the File
        instance is destructed
于 2012-07-15T13:00:21.540 回答