質問

Pythonでdocstringを書くのにいくつかの異なるスタイルを見たことがありますが、最も人気のあるスタイルは何ですか？

どのように解決するのですか？

フォーマット

Pythonのdocstringは、他の記事で紹介したように、いくつかのフォーマットに従って書くことができます。しかし、Sphinxのデフォルトのdocstringのフォーマットは言及されておらず、そのベースとなっているのは reStructuredText (reST) . 主なフォーマットに関する情報は、以下のサイトをご覧ください。 このブログの記事 .

なお、reSTが推奨しているのは PEP 287

以下は、docstringに使用される主なフォーマットです。

- エピーテキスト

歴史的に ジャバドック のようなスタイルが一般的だったので、それをベースにして エピドック (と呼ばれるもの）。 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
"""

- 再ST

現在では、おそらくより一般的な形式は 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は自社で フォーマット がよく使われます。また、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.
"""

偶数 その他の例

- ヌンピドック

なお、Numpyでは、独自の ニューピドック は、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
"""

変換・生成

のようなツールを使用することが可能です。 支払い を使えば、まだドキュメント化されていないPythonプロジェクトのdocstringを自動的に生成したり、既存のdocstring（複数の形式が混在していることもあります）をある形式から別の形式に変換したりすることができます。

注：この例は Pyment ドキュメント