docstring の style
案件で様々なstyleのdocstringを書いていると、つい混ざってしまうため自分の整理用にまとめます。
reStructuredText
def func(arg1, arg2, arg3):
"""Hello, func
Lorem ipsum dolor sit amet,
:param string arg1: First argument
:param arg2: Second argument
:type args2: list[int]
:param arg3: Third argument
:type args3: dict[str, int]
:return: Return value
:rtype: str or None
:raises ValueError: if arg1 is empty string.
"""
- param, parameter, arg, argument, key, keyword: 引数の説明です。
- type: 引数の型です。可能ならリンクを生成します。
- raises, raise, except, exception: この中から投げられる例外(いつ投げられるか？)を定義します
- var, ivar, cvar: 変数の説明をします
- vartype: 変数の型です。可能ならリンクを生成します。
- returns, return: 返り値の値について説明をします
- rtype: 返り値の型です。可能ならリンクを生成します。
Sphinxドメイン — Sphinx 1.7.10+ ドキュメント
Google style
def func(arg1, arg2, arg3):
"""Hello, func
Lorem ipsum dolor sit amet,
Args:
arg1 (str): First argument
arg2 (list[int]): Second argument
arg3 (dict[str, int]): Third argument
Returns:
str or None: Return value
Raises:
ValueError: if arg1 is empty string.
"""
Args:
各変数名の一覧を記載します。 名前の後に、コロンとスペースで区切った説明を書きます。 説明が 80 文字で収まらない場合は、2 文字か 4 文字のぶら下げインデントを使います。
Returns: (ジェネレータの場合は Yields:)
型と戻り値のセマンティクスを説明します。 関数が None しか返さない場合は、このセクションは必須ではありません。
Raises:
インターフェースに関連するすべての例外の一覧を記載します
Google Python スタイルガイド — PyGuide - 2.29
セクション一覧
- Args (alias of Parameters)
- Arguments (alias of Parameters)
- Attributes
- Example
- Examples
- Keyword Args (alias of Keyword Arguments)
- Keyword Arguments
- メソッド
- Note
- Notes
- Other Parameters
- Parameters
- Return (alias of Returns)
- Returns
- Raises
- References
- See Also
- 課題
- Warning
- Warnings (alias of Warning)
- Warns
- Yield (Yieldsの別名)
- Yields
sphinx.ext.napoleon – NumPy および Google スタイルの docstring をドキュメントに取り込む — Sphinx 1.5.6 ドキュメント
GoogleスタイルのPython Docstringsの例 — Sphinx 1.5.6 ドキュメント
Numpy style
def func(arg1, arg2, arg3):
"""Hello, func
Lorem ipsum dolor sit amet,
Parameters
-------
arg1 : str
First argument
arg2 : list[int]
Second argument
arg3 : dict[str, int]
Third argument
Returns
-------
str or None
Return value
Raises
-------
ValueError
if arg1 is empty string.
"""