標準のPython Docstring形式は何ですか？ [閉まっている

https://stackoverflow.com/questions/3898572

29-09-2019
|

質問

PythonでDocstringsを書くいくつかの異なるスタイルを見てきましたが、公式または「合意された」スタイルはありますか？

解決

フォーマット

Python Docstringsは、他の投稿が示したように、いくつかの形式に従って書くことができます。ただし、デフォルトのスフィンクスドキュストリング形式は言及されておらず、に基づいています crompructuredtext（ret）. 。メインフォーマットに関する情報を取得できますあの鼓動.

残りは、によって推奨されることに注意してください PEP 287

Docstringsのメイン使用されたフォーマットに従います。

- epytext

歴史的にa Javadoc スタイルが普及していたように、それはの基盤と見なされました 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
"""

- 残り

今日、おそらくより一般的な形式はです rustructuredText （REST）使用される形式スフィンクスドキュメントを生成します。注：デフォルトでは、JetBrains Pycharm（メソッドを定義してEnterを押した後にトリプル引用符を入力）で使用しています。また、デフォルトでは、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には独自のものがありますフォーマットそれはよく使用されます。また、Sphinxによって解釈することもできます（つまり、使用ナポレオンプラグイン).

例：

"""
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

Numpyは自分のものに従うことをお勧めします numpydoc Google形式に基づいて、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 まだ文書化されていないPythonプロジェクトにDocstringsを自動的に生成するか、既存のドキュストリング（いくつかの形式を混合することができます）をフォーマットから他のドキュメントに変換します。

注：例はから取得されます Pymentドキュメント

他のヒント

Googleスタイルガイド優れたPythonスタイルガイドが含まれています。含まれています読みやすいDocstring構文の規則 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

これに記載されているように、引数にタイプ情報も含めるようにこれを拡張するのが好きです Sphinxドキュメントチュートリアル. 。例えば：

def add_value(self, value):
    """Add a new value.

       Args:
           value (str): the value to add.
    """
    pass

Docstringの規則があります PEP-257 PEP-8よりもはるかに詳細。

ただし、Docstringsは他のコード領域よりもはるかに個人的なものであるようです。さまざまなプロジェクトには独自の標準があります。

彼らは機能を使用する方法とそれが非常に迅速に行うことを示す傾向があるため、私は常にDocstringsを含める傾向があります。

文字列の長さに関係なく、物事を一貫性を保つことを好みます。インデントと間隔が一貫しているときにコーディングする方法が好きです。つまり、私は次のことを意味します：

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

つまり、このように始まるDocstringsが乱雑になることを意味します。

def sq(n):
    """Return the squared result. 
    ...

明らかに誰も言及していないように：あなたは Numpy Docstring標準. 。科学コミュニティで広く使用されています。

形式の仕様 numpyから例
あなたはそれをレンダリングするためのスフィンクス拡張機能を持っています： numpydoc
そして、レンダリングされたドクストリングがどれほど美しいかの例： http://docs.scipy.org/doc/numpy/reference/generated/numpy.mean.html

グーグルスタイルのドキュマーを解析するためのナポレのスフィンクス拡張機能（@nathanの回答で推奨）もnumpyスタイルのドキュメントをサポートし、短いものにします比較両方の。

そして最後に、それがどのように見えるかをアイデアするための基本的な例です。

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プロジェクトを文書化するための事実上の標準です。製品は美しいです - 見てください https://python-guide.readthedocs.org/en/latest/ 。ウェブサイトドキュメントを読んでくださいドキュメントを無料でホストします。

ウラジミール・ケレシェフを使うことをお勧めします PEP257 ドキュストリングを確認するためのPythonプログラム PEP-257 そしてその Numpy Docstring標準パラメーター、リターンなどを説明するため。

PEP257は、標準から行う発散を報告し、PylintやPEP8のように呼ばれます。

ライセンス： CC-BY-SA と帰属

所属していません StackOverflow