Pythonの関数（メソッド）の内容に合わせてdocstringのテンプレートを生成してくれるautoDocstringというVS Codeの拡張機能をお仕事とプライベートで使っていたら結構気に入ったのでその紹介です。
autoDocstringでできること
- Pythonの関数やメソッドの引数名や型アノテーションなどに応じたdocstringのテンプレートをVS Code上で生成してくれます。
- ※JSDoc的なもの含め、他の言語だと割とその辺をしっかり生成してくれる一方でPythonだと（出力されるdocstringのスタイルがずれていたりなど）個人的にしっくりくるものが無く、今まではスニペット的にクリップボードへ定型文登録などして過ごしていました。
- PEP257やGoogleスタイル、NumPyスタイルなどメジャー所のdocstringのスタイルはサポートされています。
※そもそもdocstringとはなんぞや・・・という方は必要に応じて以下の記事などをご確認ください。
インストール
特に煩雑な対応は必要なく、普通にVS Codeの拡張機能の一覧でautoDocstringなどと検索してインストールするのみです。
設定を行う
インストール後にVS Codeの設定画面でautoDocstringなどと検索すると設定が色々出てきます。
色々と設定はありますが、私は以下の2点を変更しています。
docstringのスタイル
PEP257やGoogleスタイル、NumPyスタイルと色々なdocstringのスタイルがありますが、私は仕事もプライベートのPythonプロジェクトも両方ともNumPyスタイルを使っているためまずはスタイルはNumPyに変更していきます。
Docstring Formatという設定で変更することができます。numpyがNumPyスタイルとなります。
これはプロジェクトに応じて様々だと思いますのでプロジェクトに合わせて選択してください。
クォーテーションの後に改行を入れるかどうか
私は基本的にクォーテーション（"""）の後に改行を入れて説明文を書くことが多いのでStart On New Lineにチェックを入れておきます。
実際に使ってみる
以下のような適当な関数で試してみます。
from typing import List
def sample_func(name: str, ids: List[int]) -> List[str]:
...
使い方は簡単で、関数内で"""といったようにdocstring用の３つの連続したダブルクォーテーションを入力するとGenerate Docstringというメニューが表示されるので十字キーで選択してEnterを押せばDocstringのテンプレートが生成されます。
対象のメニューを選択すると以下のようにテンプレートが生成されます。引数名や型アノテーションの内容も反映されます。
最初は関数の概要部分にフォーカスが当たっており、編集が終わったらTabキーを押すことで次のフォーカスの個所に切り替えることができます（対象の各個所にハイライトがされている状態であれば）。
軽く使っていた感じ、NumPyスタイルの場合以下のような注意点があります。
- 返却値部分は
result : strといったように返却値名も書かれたりしますが、生成されるdocstringでは型のみの表示となるため必要な場合には自分で書き足す必要があります。 - 文字列のリストといったケースではNumPyスタイルでは
list of strといったような書き方がされることが結構ありますがこの辺りは型アノテーションそのままでList[str]とかlist[str]といった具合に設定されます。
余談
以前以下の記事で書いたようにNumPyスタイルのdocstringのLintを作っていまだにずっと使っているのですが、説明などが漏れていた場合にはチェックに引っかかるもののautoDocstringを使って_summary_や_description_といった記述になっていてもそのままLintを通ってしまうので、その辺に説明などがなっていたら弾く・・・といったようにアップデートをそのうちしておきたいところです・・・（そのうち仕事などで_description_などの表記のままうっかりコミットなどしそうな気がします・・・）。
参考サイト