☰

最も一般的な Python ドキュメント文字列の形式は何ですか? [closed] 質問する

tag-icon • tag-icon python coding-style documentation docstring
最も一般的な Python ドキュメント文字列の形式は何ですか? [closed] 質問する

Python で docstring を書くためのいくつかの異なるスタイルを見てきましたが、最も人気のあるスタイルは何ですか?

ベストアンサー1

フォーマット

Pythonのdocstringは、他の投稿で紹介されているように、いくつかの形式で記述できます。ただし、デフォルトのSphinxのdocstring形式については触れられておらず、reStructuredText（reST）に基づいています。主な形式に関する情報は、このブログ投稿。

reSTは、ペップ287

以下に、docstring に使用される主な形式を示します。

- エピテキスト

歴史的にはJavadocのようなスタイルが普及していたため、それがベースとして採用されました。エピドック(呼び出された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
"""

- 休む

現在、おそらくより普及しているフォーマットは、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には独自のフォーマットよく使われる。また、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は独自のnumpydocGoogle 形式に基づいており、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 ドキュメント

おすすめ記事