有没有针对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 Python Style Guide），它的对应物如下所示：

Args:
    path (str): 要包装的文件路径
    field_storage (FileStorage): 要包装的 FileStorage 实例
    temporary (bool): 当 File 实例被销毁时是否删除该文件

非常好！但当然，Sphinx 不会接受这一点，并将 Args: 后面的所有文本渲染为一行。

因此，总结一下，在我玷污我的代码库之前，我想知道除了编写自己的 API 文档之外，是否有任何真正的替代使用它和 Sphinx 的方法。例如，是否有一个处理 Google Style Guide 的文档字符串风格的 Sphinx 扩展程序？

- Hubro

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']

更多有关 napoleon 的文档 在此处。

- Relentless Idiot

---

拿破仑比Numpydoc更好，从1.3.1版本开始作为sphinx.ext.napoleon打包在Sphinx中。这实际上是更好的答案。 - ostrokach

Answer 2

我认为目前没有比更好的工具来记录Python项目。

为了使文档字符串更加清晰，我最喜欢使用和。根据您的示例，这将如下所示：

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。

- bmu

---

“array_like” 应该改为 “可迭代的(iterable)”，另外感谢提供的链接 :-) - Hubro

我唯一的抱怨是numpydocs让你最终得到2个模块链接，一个是py-modules，另一个是np-modules。 - Mark Mikofski

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

我会尝试看一下sphinx是否支持它。如果不支持的话，您也可以考虑仅为此使用epydoc（尽管目前它的维护活动不是那么活跃）。

- SquareRootOfTwentyThree

---

Sphinx支持这种写法，我用这种方式编写我的文档字符串，它们可以被正确地呈现（不确定输出结果是否与OP显示的符号一样，但在源代码和渲染后的文档中都非常易读）。 - Lev Levitsky

Answer 4

实际上，reStructuredText 和 PEP8 的样式指南主要适用于编写Python标准库本身的代码，尽管很多第三方程序员也遵守这些规范。

我同意你的观点，从代码角度来看，Google对参数的样式更好。但是，你应该也可以使用sphinx生成这样的文档字符串，保留换行和缩进，如此生成文档字符串。不过，输出结果可能不像sphinxy格式那么好看。

无论如何，你不必使用sphinx，顺便说一句，sphinx的autodoc模块只是其中的一小部分。你可以使用几乎任何能够获取docstrings内容的文档生成器，例如Epydoc（支持epytext、reStructuredText，Javadoc或Plaintext）或pydoctor，甚至更通用的Doxygen。

但是毫无疑问，Sphinx非常“Pythonic”，非常方便与Python一起使用，并使您的代码与Python生态系统保持一致。我认为你不是唯一一个认为这是一个“缺陷”。也许他们将来会考虑这些抱怨，或者您甚至可以考虑自己修改autodoc模块，这应该不难，因为它是用Python编写的，这将是一个很好的练习。

- cedbeu

Answer 5

您可以使用任何格式编写文档字符串，但为了其他Python程序员的方便起见，最好使用他们已经熟悉的标记语言和工具。如果您坚持使用reST和Sphinx，他们的生活将更加轻松。

- user25148

Answer 6

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

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

顺便说一下，由于Sphinx是用Python编写的，使其接受非RST输入只需要编写少量Python代码即可。

- Borealid

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

- Davoud Taghawi-Nejad