对于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

你必须真正放慢脚步,花一点时间才能理解这种语法混乱.我更喜欢谷歌方式(谷歌Python风格指南),与上面的对应方式如下:

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扩展,它解析了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']

这里有更多关于拿破仑的文件.

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

(一个完整的例子就是这里),HTML输出将如下所示

我认为rst文件的结构更清晰,更易读.该指南提供了更多信息和惯例.该numpydoc扩建工程用autodoc为好.

Answer 3

我使用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(尽管现在还没有积极维护).

Answer 4

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

我同意你的看法,从代码的角度来看,谷歌的论证风格要好得多.但是,你应该能够与狮身人面像产生这样的文档字符串,以及,新行和缩进保存.它的输出效果不如使用更多的sphinxy格式.

无论如何,你不必须使用狮身人面像,并顺便说一下,在autodoc狮身人面像的模块绝对是它只是一小部分.您几乎可以使用能够检索文档字符串内容的任何文档生成器,例如Epydoc(支持epytext以及reStructuredText,Javadoc或Plaintext)或pydoctor,甚至是像Doxygen这样更通用的文档生成器.

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