什么是标准的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您的文档。