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

フォーマット

他の投稿が示したように、Python docstringはいくつかの形式に従って記述できます。ただし、デフォルトのSphinx docstring形式は言及されておらず、reStructuredText（reST）に基づいています。このブログ投稿では、主なフォーマットに関する情報を入手できます。

reSTはPEP 287で推奨されていることに注意してください。

docstringに使用される主な形式は次のとおりです。

-Epytext

歴史的には、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
"""

- 残り

今日、おそらくより一般的なフォーマットは、ドキュメントを生成するためにSphinxによって使用されるreStructuredText（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

Googleには、よく使用される独自の形式があります。Sphinxで解釈することもできます（つまり、Napoleonプラグインを使用）。

例：

"""
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は、Google形式に基づいており、Sphinxで使用できる独自のnumpydocに従うことをお勧めします。

"""
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プロジェクトにドキュメント文字列を自動的に生成したり、既存のドキュメント文字列（複数の形式が混在している可能性があります）を別の形式に変換したりできます。

注：例はPymentのドキュメントから引用しています

Googleのスタイルガイドは優れたPythonのスタイルガイドが含まれています。PEP-257よりも優れたガイダンスを提供する、読みやすいdocstring構文の規則が含まれています。例えば：

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よりもはるかに詳細です。

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

docstringは常に含める傾向があります。これは、関数の使用方法とその機能が非常に迅速に示される傾向があるためです。

文字列の長さに関係なく、一貫性を保つことを好みます。インデントと間隔が一貫している場合の外観のコーディング方法が好きです。つまり、私は以下を使用します。

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

つまり、このように始まるdocstringが乱雑であることがわかります。

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

どうやら誰もそれについて言及していません：Numpy Docstring Standardを使用することもできます。科学界で広く使用されています。

• numpyからのフォーマットの仕様と例
• あなたはそれをレンダリングするためのスフィンクス拡張を持っています：numpydoc
• そして、レンダリングされたdocstringがどのように美しく見えるかの例：http : //docs.scipy.org/doc/numpy/reference/generated/numpy.mean.html

Googleスタイルのドキュメント文字列（@Nathanの回答で推奨）を解析するためのNapoleanスフィンクス拡張機能は、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コーディング標準です。Docstring の完全な仕様であるPEP-257を参照する、docstringに関するセクションが含まれています。

それはPythonです。何でも行く。ドキュメントの公開方法を検討してください。Docstringは、ソースコードの読者以外は表示されません。

人々はウェブ上でドキュメンテーションを閲覧したり検索したりするのが本当に好きです。そのためには、ドキュメントツールSphinxを使用します。これは、Pythonプロジェクトを文書化するための事実上の標準です。製品は美しいです-https://python-guide.readthedocs.org/en/latest/をご覧ください。ウェブサイトのRead the Docsは無料でドキュメントをホストします。

Vladimir Keleshevのpep257 Pythonプログラムを使用して、ドキュメント文字列をPEP-257およびNumpy Docstring Standardに対してチェックし、パラメーターや戻り値などを説明することをお勧めします。

pep257は、標準からの相違を報告し、pylintおよびpep8のように呼び出されます。