112
96

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

More than 5 years have passed since last update.

docstringのstyle3種の例

Posted at

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

numpydoc docstring guide

NumPyスタイルPython Docstringsの例 — Sphinx 1.5.6 ドキュメント

112
96
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
112
96

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?