docstringしたい(sphinx.ext.napoleon
)
1# conf.py
2extensions = [
3 "sphinx.ext.napoleon",
4]
sphinx.ext.napoleonを有効にすると、docstring
をNumPyスタイルやGoogleスタイルで書けるようになります。
注釈
NumPy-styleを選ぶか、Google-styleを選ぶかはお好みです。 ただし、プロジェクト内で混在させるのはやめましょう。
VS CodeではAuto Docstring: Docstring Format
で設定できます。
デフォルトはgoogle
になっています。
Googleスタイルしたい
1def load_data(read_from: str, search_pattern: str) -> pd.DataFrame:
2 """ファイルを読み込む
3
4 必要なファイルを一括で読み込み、データフレームに変換します。
5
6 Args:
7 read_from (str): 読み込むディレクトリ名
8 search_pattern (str): 読み込むファイル名(の共通部分)
9 Returns:
10 data (pd.DataFrame): データフレーム
11 """
12 pass
Googleスタイルは、コンパクトに書けるという特徴があります。 引数の説明が短くて済む場合に最適です。
NumPyスタイルしたい
1def load_data(read_from: str, search_pattern: str) -> pd.DataFrame:
2 """ファイルを読み込む
3
4 必要なファイルを一括で読み込み、データフレームに変換します。
5
6 Parameters
7 ----------
8 read_from : str
9 読み込むディレクトリ名
10 search_pattern : str
11 読み込むファイル名(の共通部分)
12
13 Returns
14 -------
15 data : pd.DataFrame
16 データフレーム
17 """
18 pass
NumPyスタイルは、縦に伸びる傾向があります。 引数の説明が長くなる場合は、こちらが適しています。