Question

我即将开始一个开源Python项目，我正在尝试提前决定如何编写我的文档字符串。显而易见的答案是使用reStructuredText和Sphinx与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），与上面的对应方式如下：

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

方式更好！但是，当然，Sphinx将没有这一点，并在“Args：”之后的所有文本中显示一条长行。

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

Answer 1

我创建了一个Sphinx extension来解析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']

有关拿破仑here的更多文档。

Answer 2

我认为目前没有比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输出看起来像this

我认为rst文件的结构更清晰，更易读。 guide提供了更多信息和约定。 numpydoc扩展程序也适用于autodoc。

Answer 3

我使用epydoc而不是狮身人面像，所以这个答案可能不适用。

您描述的用于记录方法和函数的reStructuredText语法不是唯一可能的语法。到目前为止，我更喜欢使用consolidated definition list来描述参数，这与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（尽管现在不是主动维护）。

Answer 4

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

我同意你的看法，从代码的角度来看，谷歌的论证风格要好得多。但您也应该generate such docstring with sphinx，with the new lines and indentation preserved。它的输出效果不如with a more sphinxy formatting那么好。

无论如何，你不必须使用sphinx，顺便说一句，sphinx的autodoc模块绝对只是其中的一小部分。您几乎可以使用任何能够检索文档字符串内容的文档生成器，例如Epydoc（支持epytext以及reStructuredText, Javadoc or Plaintext）或pydoctor，甚至是比较普遍的Doxygen。

但是，绝对是，sphinx非常适合 pythonic ，非常方便与Python一起使用，并使您的代码与Python的生态系统保持一致。我认为你是not the only one谁认为这是“缺乏”。也许他们将来会考虑这些投诉，或者你甚至可能会考虑自己模拟autodoc模块，不应该非常困难，这是Python，这将是一个很好的练习。

Answer 5

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

Answer 6

Python使文档字符串的内容可用作附加到函数/类/变量对象的__doc__属性。

所以，你可以轻而易举地编写一个Python程序，将你喜欢的任何格式的文档转换成你喜欢的任何格式。您甚至可以使用Javadoc样式，XML或其他任何东西。

顺便说一句，由于Sphinx是用Python编写的，因此只需编写少量Python代码就可以进行非RST输入。

Answer 7

您只需要开始一个新行并在每个变量名后添加一个点按。然后使用持久性粗体变量名称在多行中进行渲染：

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

对于Python文档，reStructuredText有什么真正的替代品吗？

7 个答案: