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

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。

无论如何，你不必使用狮身人面像，顺便说一下，狮身人面像的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编写的，因此非RST输入只需要编写少量的Python代码。

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