我开始不久，一个开源Python项目，我想提前决定如何写我的文档字符串。 答案显然是使用新结构化和狮身人面像车博士，因为我真的很喜欢的只是适当记录我的代码在我的文档字符串的想法，然后有狮身人面像自动构建的API文档我。
问题是，它采用了新结构化的语法 - 我认为这是渲染之前它是完全不可读。 例如：
: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
方式更好！ 但当然，狮身人面像将有没有这一点，并呈现后的所有文字“参数数量：”在一个长行。
因此，要总结 - 在我走之前，用这种新结构化的语法，我想知道是否有使用它和狮身人面像任何真正的选择玷污我的代码库，短的只写我自己的API文档。 例如，是否有狮身人面像的扩展，处理谷歌风格指南的文档字符串风格？
Answer 1:
我创建了一个狮身人面像的扩展 ，将分析这两个谷歌的风格和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输出将看起来像这样
我觉得第一个文件的结构更清晰，更具可读性。 该指南给出了一些更多的信息和约定。 该numpydoc扩展与工程autodoc为好。
Answer 3:
我用epydoc的 ，而不是狮身人面像，所以这个答案可能并不适用。
你描述的记录方法和功能的新结构化的语法是不是唯一可能的一个。 到目前为止，我更喜欢使用描述参数综合定义列表 ，这是非常类似谷歌的方法：
: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的只是那个（虽然这是不对的，现在积极maintaned）。
Answer 4:
事实上， 新结构化以及风格指南PEP8大多申请编码Python的标准库本身，虽然很多第三方程序员符合该为好。
我同意你的是，谷歌的风格参数是从同代码的角度更好。 但是，你应该能够与狮身人面像产生这样的文档字符串 ，以及， 新行和缩进保存 。 它不输出像你一样有更多的sphinxy格式虽然。
无论如何，你不必使用狮身人面像，并顺便说一下，在autodoc狮身人面像的模块绝对是它只是一小部分。 您几乎可以使用任何文档生成器，它能够检索文档字符串的内容，像epydoc的 （支持epytext以及新结构化，或的Javadoc明文 ）或pydoctor ，甚至更普遍的一个类似的Doxygen 。
但可以肯定，狮身人面像很Python的 ，非常方便与Python使用，使你的代码与Python的生态系统是一致的。 我想你是不是唯一一个谁认为这是一个“缺乏”。 也许他们会采取这些投诉考虑在未来，也许你甚至可以考虑modyfying的autodoc自己模块，应该不是很困难的，这是在Python，这将是一个很好的锻炼。
Answer 5:
你可以写在你喜欢的任何格式的文档字符串。 然而，对于所有其他Python程序员的缘故，最好使用标记，他们已经知道的工具。 如果你坚持到休息和狮身人面像他们的生活更容易。
Answer 6:
蟒使得文档字符串的内容可作为__doc__附连到的功能/类/可变对象属性。
所以，你可以写平凡，从你喜欢到你喜欢的任何格式的任何格式的文件转换成一个Python程序。 你甚至可以使用的Javadoc的造型，或XML，或什么的。
顺便说一句，因为狮身人面像用Python编写的，使得它采取非RST输入只是写的Python代码量小的问题。
Answer 7:
你只需要启动一个新的行，每个变量名称后添加一个水龙头。 然后，它呈现在几行consucutive大胆的变量名：
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
文章来源: Are there any real alternatives to reStructuredText for Python documentation? [closed]
