docstring (Google スタイル)で複数の Returns を Sphinx に反映させる方法
Python のドキュメントを作るためのジェネレータ Sphinx を利用する際に、 Google Style で docstring を書いたとき、Returns が複数ある場合にうまく反映されない現象に対処する方法のメモです。
extensions として autodoc と napoleon を使っています。
解決策の結論
Sphinx の conf.py に以下のような記述を足す。
napoleon_custom_sections = [('Returns', 'params_style')]問題
Sphinx で Python プログラムのドキュメントを作る際にはソースコード内に docstirng 形式でコメントを書き込みます。この docstring にはいくつかの記法が知られており、その一つが Google Style です。
以下のプログラムは Google Style で docstring を書いてみた例です。返り値が二つあるタイプの関数です。
def hoge(a, b):
""" 関数の説明.
Args:
a (float): 一つ目の数.
b (float): 二つ目の数.
Returns:
result_sum (float): 足し算の結果.
result_prod (float): 掛け算の結果.
"""
result_sum = a + b
result_prod = a * b
return result_sum, result_prodこれを Sphinx を使ってドキュメント化すると以下のようになります。
Returns に書いた内容が羅列されるのではなく、最初の変数名と型だけが「戻り値の型」にされて、残りは全部ひとまとめに書かれています。デフォルトでは戻り値は 1 つだけであるという前提のようです。
複数の戻り値を羅列させる
引数のように戻り値も羅列させるためには Sphinx の設定 conf.py に以下の行を書き加えます。
napoleon_custom_sections = [('Returns', 'params_style')]設定を保存してドキュメント化を実行すると以下のようになります。
「戻り値」が「Returns」になってしまいますが、先ほどよりは見やすくなりますね。