对于Python文档，是否有其他真正的替代方法？

我很快就要开始一个开放源码的Python项目，我正试图提前决定如何编写我的docstring。显而易见的答案是将StructuredText和Sphinx与

autodoc

一起使用，因为我非常喜欢这样的想法，即只需在我的docString中正确地记录我的代码，然后让Sphinx自动为我构建一个API文档

问题在于它使用的StructuredText语法——我认为在呈现之前它是完全不可读的。例如：

: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 way（），它与上面的内容类似：

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 Args： path（str）：要包装的文件的路径 field_storage（FileStorage）：要包装的FileStorage实例 临时（bool）：文件删除时是否删除文件 实例被破坏 方式更好！但当然，Sphinx将不包含这些内容，而是将

Args:

之后的所有文本渲染成一行

---

总之，在我开始用这种重构的文本语法玷污我的代码库之前，我想知道除了编写自己的API文档之外，是否还有其他真正的替代方法来使用它和Sphinx。例如，Sphinx是否有一个扩展来处理Google Style Guide的docstring样式？

Python将docstring的内容作为附加到函数/类/变量对象的

\u doc\u

属性提供

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

顺便说一句，由于Sphinx是用Python编写的，因此采用非RST输入只是编写少量Python代码的问题。

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

我同意你的观点，从代码角度来看，谷歌的参数风格要好得多。但是你也应该能够。它的输出并不像看上去那么好

无论如何，您不必使用sphinx，顺便说一句，sphinx的

autodoc

模块肯定只是其中的一小部分。实际上，您可以使用任何能够检索docstring内容的文档生成器，如（支持）或（甚至是更通用的）

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

< P>你可以以任何你喜欢的格式写文档字符串。然而，对于其他所有Python程序员来说，最好使用他们已经知道的标记和工具。如果你坚持休息和斯芬克斯，他们的生活会更轻松。

我使用斯芬克斯而不是斯芬克斯，所以这个答案可能不适用

您描述的用于记录方法和函数的reStructuredText语法并不是唯一可能的语法。到目前为止，我更喜欢使用a来描述参数，这与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支持，我会尝试一下。如果没有，你也可以考虑使用EyDoc来做这个（虽然它现在不是主动维护的）。

< P>我不认为有什么比“代码>狮身人面像< /代码>更适合目前记录Python项目。

要获得更清晰的文档字符串，我最喜欢的选择是将

sphinx

与。根据您的示例，这看起来像：

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

一起使用。

您只需在每个变量名称后开始一行并添加一个点击。然后，它将以简洁的粗体变量名呈现在几行中：

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

我已经创建了一个解析Google风格和NumPy风格的docstring，并将它们转换为标准的StructuredText

要使用它，只需安装它：

$ pip install sphinxcontrib-napoleon 

并在conf.py中启用它：

# conf.py

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

---

更多关于napoleon的文档。

Sphinx确实支持这一点，我用这种方式编写了docstring，它们呈现得很好（不确定输出是否与OP显示的符号相同，但在源代码和呈现的文档中都非常可读。）“array_like”不应该是“iterable”吗？还要感谢链接：-）我对numpydocs唯一的抱怨是，您最终得到了两个模块链接，一个用于py模块，另一个用于np-modules。Napoleon比Numpydoc好，从版本1.3.1开始，它以Sphinx打包，如

Sphinx.ext.Napoleon

。这实际上是更好的答案。