什么是标准的Python文档string格式？
我已经看到了用Python编写文档的几种不同风格，是否有官方的或“同意”的风格？
格式
Python文档可以按照其他post显示的几种格式编写。 然而，默认的Sphinx docstring格式没有被提及，并且基于reStructuredText（reST） 。 你可以得到一些关于主要格式的信息。
请注意，PST 287build议使用reST
接下来是文档的主要使用格式。
– Epytext
从历史上看，类似javadoc风格是stream行的，所以它被当作Epydoc （用所谓的Epytext格式）生成文档的基础。
例：
""" This is a javadoc style. @param param1: this is a first param @param param2: this is a second param @return: this is a description of what is returned @raise keyError: raises an exception """
– 重试
现在，可能更普遍的格式是由Sphinx用来生成文档的reStructuredText （reST）格式。 注意：在JetBrains PyCharm中默认使用（在定义方法并按回车后键入三重引号）。 它也被默认用作Pyment中的输出格式。
例：
""" This is a reST style. :param param1: this is a first param :param param2: this is a second param :returns: this is a description of what is returned :raises keyError: raises an exception """
– 谷歌
Google有自己常用的格式 。 它也可以被狮身人面像解释。
例：
""" This is an example of Google style. Args: param1: This is the first param. param2: This is a second param. Returns: This is a description of what is returned. Raises: KeyError: Raises an exception. """
更多的例子
– Numpydoc
请注意，Numpybuild议遵循基于Google格式的自己的numpydoc ，并可以使用Sphinx。
""" My numpydoc description of a kind of very exhautive numpydoc format docstring. Parameters ---------- first : array_like the 1st param name `first` second : the 2nd param third : {'value', 'other'}, optional the 3rd param, by default 'value' Returns ------- string a value in a string Raises ------ KeyError when a key error OtherError when an other error """
转换/生成
可以使用像Pyment这样的工具自动生成文档到尚未logging的Python项目，或者将现有的文档（可以混合多种格式）从一种格式转换为另一种格式。
注意：这些例子来自Pyment文档
Google风格指南包含了极好的Python风格指南。 它包括可读文档string语法的约定，比PEP-257提供更好的指导。 例如：
def square_root(n): """Calculate the square root of a number. Args: n: the number to get the square root of. Returns: the square root of n. Raises: TypeError: if n is not a number. ValueError: if n is negative. """ pass
我喜欢把这个扩展为在参数中包含types信息，如Sphinx文档教程中所述 。 例如：
def add_value(self, value): """Add a new value. Args: value (str): the value to add. """ pass
文档string约定在PEP-257中比PEP-8更详细。
但是，文档似乎比其他代码领域更加个人化。 不同的项目会有自己的标准。
我倾向于总是包含文档，因为他们倾向于演示如何使用该function以及它如何快速地执行。
我宁愿保持一致，不pipestring的长度。 缩进和间距一致时，我喜欢如何编码。 这意味着，我使用：
def sq(n): """ Return the square of n. """ return n * n
过度：
def sq(n): """Returns the square of n.""" return n * n
并倾向于在较长的文档中对第一行进行评论：
def sq(n): """ Return the square of n, accepting all numeric types: >>> sq(10) 100 >>> sq(10.434) 108.86835599999999 Raises a TypeError when input is invalid: >>> sq(4*'435') Traceback (most recent call last): ... TypeError: can't multiply sequence by non-int of type 'str' """ return n*n
这意味着我发现这样开始的文档会变得混乱。
def sq(n): """Return the squared result. ...
至于没有人提到它：你也可以使用Numpy Docstring Standard 。 它在科学界被广泛使用。
- numpy 格式的说明和一个例子
- 你有一个狮身人面像扩展来渲染它： numpydoc
- 下面是一个渲染文档string如何漂亮的例子： http : //docs.scipy.org/doc/numpy/reference/generated/numpy.mean.html
用于parsingGoogle风格文档string（在@Nathan的答案中推荐）的Napolean sphinx扩展也支持Numpy风格的文档string，并对两者进行了简短的比较 。
最后给出一个基本的例子来说明它的外观：
def func(arg1, arg2): """Summary line. Extended description of function. Parameters ---------- arg1 : int Description of arg1 arg2 : str Description of arg2 Returns ------- bool Description of return value See Also -------- otherfunc : some related other function 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] """ return True
PEP-8是官方的Python编码标准。 它包含一个关于docstrings的部分，它指的是PEP-257–一个完整的docstrings规范。
Python的官方风格列在PEP-8中 。
我build议使用Vladimir Keleshev的pep257 Python程序检查您的文档反对PEP-257和Numpy Docstring标准来描述参数，返回等。
pep257会报告你从标准中产生的分歧，并被称为像pylint和pep8。
这是Python; 什么都行 考虑如何发布您的文档 。 除了源代码的读者以外，Docstrings是不可见的。
人们真的喜欢在网上浏览和search文档。 要实现这一点，请使用文档工具Sphinx 。 这是loggingPython项目的事实标准。 该产品是美丽的 – 看看https://python-guide.readthedocs.org/en/latest/ 。 阅读文档网站将免费托pipe您的文档。
