有没有真正的替代Python文档的reStructuredText？
我很快就开始了一个开源的Python项目，并且正在尝试提前决定如何编写我的文档。 显而易见的答案是将reStructuredText和Sphinx与autodoc结合使用，因为我非常喜欢简单地在我的文档中恰当地logging我的代码的想法，然后让Sphinx自动为我构build一个API文档。
问题是它使用的reStructuredText语法 – 我认为它在呈现之前是完全不可读的。 例如：
：param path：要包装的文件的path
：inputpath：str
：param field_storage：要包装的：class：`FileStorage`实例
：inputfield_storage：FileStorage
：param temporary：是否在File实例中删除文件
被破坏
：inputtemporary：bool
你必须真的放慢速度，花一点时间去理解这种句法混乱。 我更喜欢谷歌的方式（ 谷歌Python风格指南 ），与上述相对应的是这样的：
ARGS：
path（str）：要包装的文件的path
field_storage（FileStorage）：要包装的FileStorage实例
临时（bool）：文件是否删除时的文件
实例被破坏
更好！ 但是，当然，狮身人面像将不会有这样的东西，并且在“长矛”之后把所有的文字都排成一列。
所以总结一下 – 在我用这个reStructuredText语法去玷污我的代码库之前，我想知道是否有任何真正的替代方法来使用它和Sphinx，而不仅仅是编写我自己的API文档。 例如，是否有一个处理Google Style Guide文档string样式的Sphinx扩展？
我不认为有什么比sphinx文件目前的Python项目更好。
要有一个更清晰的文档string，我最喜欢的select是与numpydoc一起使用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输出将如下所示
我认为第一个文件的结构更清晰，更可读。 指南提供了更多的信息和约定。 numpydoc扩展也适用于autodoc 。
我创build了一个Sphinx扩展 ，用于parsingGoogle样式和NumPy样式文档，并将其转换为标准reStructuredText。
要使用它，只需安装它：
$ pip install sphinxcontrib-napoleon
并在conf.py中启用它：
# conf.py # Add autodoc and napoleon to the extensions list extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.napoleon']
拿破仑的更多文档在这里 。
我使用epydoc而不是狮身人面像，所以这个答案可能不适用。
您描述的logging方法和函数的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（虽然现在还没有被积极维护）。
实际上， reStructuredText以及PEP8的风格指南主要适用于Python标准库自身的编码，尽pipe很多第三方程序员也一样。
我同意你的观点，从代码的angular度来看，Google对于论点的风格要好得多。 但是你也应该能够用狮身人面像来生成这样的文档string， 并保留新的行和缩进 。 它不会像使用更多的sphinxy格式那样输出。
无论如何，你不必使用狮身人面像，顺便说一句，狮身人面像的autodoc模块绝对只是它的一小部分。 您几乎可以使用任何能够检索docstrings内容的文档生成器，如Epydoc （支持epytext以及reStructuredText，Javadoc或Plaintext ）或pydoctor ，或者甚至是像Doxygen这样更通用的文档生成器。
但是，sphinx绝对是pythonic ，使用Python非常方便，并使您的代码与Python生态系统保持一致。 我认为你不是唯一认为这是“缺乏”的人。 也许他们将来会把这些抱怨考虑进去，或者你甚至可能会考虑自己来autodoc模块，不应该很困难，这是Python中的，这将是一个很好的练习。
你可以用你喜欢的任何格式编写文档。 但是，为了其他Python程序员，最好使用他们已经知道的标记和工具。 如果你坚持使用reST和狮身人面像，他们的生活会更容易。
Python将docstrings的内容作为附加到函数/类/variables对象的__doc__属性提供。
所以，你可以简单地编写一个Python程序，把你喜欢的任何格式的文档转换成你喜欢的任何格式。 你甚至可以使用Javadoc样式，或XML，或其他。
顺便说一句，因为Sphinx是用Python编写的，所以使用非RSTinput只是编写less量的Python代码。
你只需要开始一个新的行，并添加每个variables名后面的水龙头。 然后用几行粗体variables名称来呈现它们：
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
