- 1. 概要
- 2. インストール
- 3. 操作
- 4. カスタマイズ
- 5. 参考サイト
1. 概要
「Python」のドキュメント化の拡張機能です。
2. インストール
ドキュメント化は、「Python Docstring Generator」という拡張機能をインストールするのがよいかと思います。
3. 操作
ソース内で、「"""」を入力すると「Generate docstring」という入力補助が表示されますので
Enter
するとドキュメント入力用のテンプレートが出力されます。
だがしかし、関数の場合、関数の下でないと表示されないのです。
わたしは、関数の上に置きたい。
更に、文字列表示の色になっていて、コメント色ではない。
この色を変更する設定をまだ知らないのです（2021年4月21日）。
なので、自分で上に持って行って、コメントアウトするという面倒なことをしています。
ドキュメントの形式は
・dockblockr
・google
・sphinx
・numpy
というものの中から選択できるようです。
わたしは、よう知らんのですが、「sphinx」というものを使用しています。
4. カスタマイズ
ちょっとこれ、いじってみようかと思っております。
かっこよくいうと、カスタマイズですな。
拡張機能のあるファイルの場所を示します。
プラットフォームやバージョンが変われば、フォルダ名も変わりますのでご注意。
上位のパスは省略します。
「Windows」の場合、上位のパスは
C:\\Users\ユーザ名.vscode\extensions
で、拡張機能は下記にあります。
/パス/njpwerner.autodocstring-0.5.4
入力候補を「"""」と判断するのが、
out/parse/get_docstring.js
かな。
テンプレートが、下記に用意されています。
out/docstring/templates/*.mustache
まずは、自分用のテンプレートを作成。
「shinx.mustache」をコピーして、下記を作成します。
out/docstring/templates/mine.mustache
テンプレートの候補として、「mine」を選択できるようにします。
package.json
を編集します。
"keywords": [
"python",
"docstring",
"google",
"numpy",
"sphinx",
"generator",
"autodocstring",
"docblockr",
"pydocstring"
],
にキーワードとして、「"mine",」という行を加えます。
"configuration": {
"type": "object",
"title": "Python Docstring Generator configuration",
"properties": {
"autoDocstring.docstringFormat": {
"type": "string",
"default": "google",
"enum": [
"docblockr",
"google",
"sphinx",
"numpy"
],
「"enum"」内に、これも「"mine",」という行を加えます。
これで「Setting.json」に
"autoDocstring.docstringFormat": "mine",
を設定してもエラーにならなくなります。
次に
out/docstring/get_template.js
を編集します。
function getTemplate(docstringFormat) {
switch (docstringFormat) {
case "google":
return getTemplateFile("google.mustache");
case "sphinx":
return getTemplateFile("sphinx.mustache");
case "numpy":
return getTemplateFile("numpy.mustache");
default:
return getTemplateFile("default.mustache");
}
}
11行と12行の間に、以下の 2行を加えます。
case "mine":
return getTemplateFile("mine.mustache");
後は、「mine.mustache」を自分の思う書式で記述していけば、ある程度、思い通りになります。
今んとこ（2021年7月1日）ここまでです。
また、何か目立って編集したら、書きます。
5. 参考サイト
本ページは、下記のサイトを参考にさせていただきました。
「VisualStudioCodeでPythonのコメント記述の補助を行うautoDocstringを利用する - MRが楽しい」
|
