VSCodeの拡張機能「autoDocstring」の使い方とドキュメンテーション文字列を自動生成する方法について解説します。
拡張機能「autoDocstring」とは
VSCodeの拡張機能「autoDocstring」は、以下のようなPythonの関数／メソッドやクラスのDocstringを自動生成します。引数や戻り値も自動で解析してくれます。
def greet(name: str, age: int = 0) -> str:
"""
Summary line.
Parameters
----------
name : str
Description of name.
age : int, optional
Description of age (default is 0).
Returns
-------
str
Description of return value.
"""
return f"Hello, {name}!"
今回は、VSCodeの拡張機能「autoDocstring」の導入方法と使い方について解説します。
拡張機能のインストール
① Visual Studio Code を起動します。
② 左側の 拡張機能アイコン（四角が4つ） をクリックします。
③ 検索バーに「autoDocstring」と入力します。
④ 「autoDocstring – Python Docstring Generator」を選択して [インストール] をクリックします。
基本的な使い方
① VSCodeでPythonファイルを開き、docstring を生成したい「関数」や「クラス」の中にカーソルを置きます。
② ダブルクォーテーション３つ「”””」を入力すると「Generate Docstring」というメニューが表示されます。
③ Enterキーでテンプレートが挿入されます。
④ Tabキーで各項目にフォーカス移動しながら編集できます。
実行例
① 以下の関数内にカーソルをあてます。
def add_numbers(a, b):
return a + b
② ダブルクォーテーション3つ「”””」を入力します。
def add_numbers(a, b):
"""
return a + b
③「Generate Docstring」というメニューが表示されます。Enterキーを押すと以下のようなテンプレートが挿入されます。
def add_numbers(a, b):
"""_summary_
Args:
a (_type_): _description_
b (_type_): _description_
Returns:
_type_: _description_
"""
return a + b
④ 関数の概要（summary）、引数と型（type）と説明文（description）の欄を以下のように埋めます。
def add_numbers(a, b):
"""2つの数値を受け取り、それらの合計を返します。
Args:
a (int または float): 最初の数値
b (int または float): 2番目の数値
Returns:
int または float: a と b の合計
"""
return a + b
⑤ 以下のように関数呼び出し（add_numbers()）を記述し、マウスのカーソルをあてると、④で記述したDocstringがヘルプ機能として表示されます。
def add_numbers(a, b):
"""2つの数値を受け取り、それらの合計を返します。
Args:
a (int または float): 最初の数値
b (int または float): 2番目の数値
Returns:
int または float: a と b の合計
"""
return a + b
add_numbers()
ドキュメントのスタイルをカスタマイズ
① VSCodeの上部メニューから、「ファイル」 → 「ユーザー設定」 → 「設定」を開きます。
② 「Docstring Format」でドキュメントのスタイルをgoogle, numpy, sphinx, pep257 などから選択します。
③ 「Start On New Line」でダブルクォーテーションの後に改行を入れるかどうか指定できます。説明文を見やすくしたい場合はチェックを入れましょう。
設定ファイルを使う場合
なお、上記については設定ファイル（settings.json）でも変更可能です。
① ショートカット「Ctrl + Shift + P」でコマンドパレットを表示し、以下を入力してEnterを押します。
※Macは「Cmd + Shift + P」
Preferences: Open User Settings (JSON)
② 以下をsettings.jsonに追加します。
【settings.json】
{
// ドキュストリングのスタイル: "google", "numpy", "sphinx" のいずれか
"autoDocstring.docstringFormat": "numpy",
// テンプレート内でクォートを 3重に使うか
"autoDocstring.includeQuotesOnTemplate": true,
// 3重クォートのタイプ。''' or """
"autoDocstring.quotesStyle": "\"\"\""
}
「プロジェクト」や「ワークスペース」単位で`settings.json` に書くと、カスタマイズしたスタイルを「プロジェクト」や「ワークスペース」で適用できます。
テンプレートの自作
自分でドキュメントのテンプレート（雛形）を生成することもできます。
① ワークスペースのルートに autoDocstring.json を作成し、以下のようにプレースホルダを定義します。
【autoDocstring.json】
{
"customTemplate": {
"function": [
"'''",
"{{summary}}",
"",
"{{#params}}:param {{name}}: {{description}}",
"{{/params}}",
":returns: {{returns}}",
"'''"
]
}
}
② settings.json でテンプレートを選択します。
【settings.json】
{
"autoDocstring.customTemplatesPath": "./autoDocstring.json",
"autoDocstring.docstringTemplate": "customTemplate"
}
【補足】GitHub Copilotとの使い分け
| 特徴 | autoDocstring | GitHub Copilot |
|---|---|---|
| 主な用途 | Docstringのテンプレート生成 | Docstring＋説明文の提案・補完 |
| スタイル選択 | Google, NumPy, Sphinxなど | プロンプトでGoogleなど色々なスタイルを指定 |
| 操作方法 | """入力でテンプレート挿入 |
コメントや /doc 指示で自動生成 |
| 精度 | テンプレート通りに生成するため安定 | 柔軟だが変動あり |
| カスタマイズ性 | 高い（設定でスタイル変更可能） | 低め（プロンプトで調整は可能） |
| 補完範囲 | 関数・メソッド単位 | 関数、クラス、ファイル全体も可能 |
| 連携性 | Lintツールと相性◎ | GitHub PagesやSphinxと連携可能 |
テンプレートベースで統一感あるドキュメントが欲しい → autoDocstringがおすすめ
柔軟な説明文を生成したい → GitHub Copilotがおすすめ
LintやPEP8準拠を重視したい → autoDocstring がおすすめ
まずは autoDocstring でベースを整え、Copilotで補足説明や背景を追加する使い分けがおすすめです。
関連ページ
コメント