Vimプラグインのヘルプドキュメントを自動生成する

この記事はVim Advent Calendar 2012 : ATND 257日目の記事です。

さらに追加された機能の記事を書きました。
- README.mdをVimのヘルプファイルから生成する - cafegale

皆さんVimプラグインを作ったことはありますか？
VACではプラグインを書いて公開するまでにやることについての記事がいくつかあります。

プラグインを作ったら、doc/以下にヘルプドキュメントを添付します。
そうすることで、:helpでいつでもドキュメントを参照することが出来ます。
ヘルプを添付しないと神様に叱られてしまいます。

しかしながら、ヘルプを書くのはプラグインを作る中でももっとも苦痛な作業のひとつです*1。
かく言う私もヘルプ不精で、ヘルプを添付せず、ソースの中に使い方を書いたコメントを書くことや、ブログの記事での紹介で済ませてしまっていることが多々あります。

だから作りました。

LeafCage/vimhelpgenerator

プラグインのヘルプを自動的に作成するプラグインです。

初期設定

以下の変数を.vimrcなどに定義します。

g:vimhelpgenerator_defaultlanguage: "ja"を指定すると日本語、"en"を指定すると英語のヘルプを作成する。
g:vimhelpgenerator_version: "Version :"の項に表示される文字列。空文字で無効。
g:vimhelpgenerator_author: "Author :"の項に表示される文字列。空文字で無効。
g:vimhelpgenerator_license: 表示するライセンスを記述したファイルの&runtimepath以下のパスを記述。既定はMIT license（変更再配布OKだけど、どこかに著作者名の記述義務）。ほかにzlib/libpng（ソース形式で配布するなら著作者名の記述義務）、NYSL（著作者名の記述の義務すらなし。）のファイルがvimhelpgenerator/以下に用意されている。空文字や読めないファイル名を指定すると無効。※
g:vimhelpgenerator_contents: 表示させるコンテンツを指定する辞書。0にしたコンテンツは表示されない。1より上の数を指定することでコンテンツの表示順を並べ替えることが出来る（若い数ほど先に表示される）。

※ライセンスというものについて、詳しくは以下の記事参照。

設定例

let g:vimhelpgenerator_version = ''
let g:vimhelpgenerator_author = 'Author  : LeafCage <leafcage+vim @ gmail.com>'
let g:vimhelpgenerator_contents = {
  \ 'contents': 1, 'introduction': 1, 'usage': 1, 'interface': 1,
  \ 'variables': 1, 'commands': 1, 'key-mappings': 1, 'functions': 1,
  \ 'setting': 0, 'todo': 1, 'changelog': 0
  \ }

使い方

まずはヘルプを作成したいプラグインのいずれかのファイルを開きます。
f:id:leafcage:20130817131015p:plain

次に、:VimHelpGeneratorコマンドを実行します。
f:id:leafcage:20130817131042p:plain

ヘルプを作成するプラグインのパスと名前を確認してくるので、間違いなければeを入力して実行します。
f:id:leafcage:20130817131056p:plain

生成されたヘルプが開かれます*2。
フォーマットは日本人プラグイン開発者の多くが使っているものを参考にしました。
（もしも日本語でヘルプを作るのなら、第一行目にマルチバイト文字を含んでください。そうしないと:helptagsしたときエラーE670が出ます。）
f:id:leafcage:20130817131358p:plain

概要や使い方は皆様の手で書くことが出来ます。
f:id:leafcage:20130817131406p:plain

変数や関数、コマンドやキーマップは、自動収集されたもので埋められます。
グローバルなものは何でも取ってくるので、公開したくないものは削除してください。
また、精度が良くないので、間違っている部分があれば修正してください（特に変数について辞書は既定値が取得できません。既定値の取得は結構いい加減です）。
それぞれの説明文は人力で埋めてください。
f:id:leafcage:20130817131417p:plain

これで随分とヘルプを作るのが楽になったはずです。
これからはヘルプ無しのプラグインを作るなんてあり得ませんね！

実は

申し訳程度に、ヘルプの出力を全面的にカスタマイズする機構も用意しています。詳しくはhelpをご覧ください。

新しいバージョンのVimでは上手く動いていませんでした。現在は動作するはずです。問題点を発見すればIssues · LeafCage/vimhelpgeneratorへ報告をお願いします。

*1:詳細なヘルプを毎回添付している先人たちには敬服します。

*2:このとき密かに.gitignoreとREADME.mdも出力していますした。:HelpIntoMarkdownコマンドが導入されたのでREADME.mdの出力はオミットされました

cafegale(LeafCage備忘録)

LeafCage備忘録（はてなダイアリー）と統一しました。

Vimプラグインのヘルプドキュメントを自動生成する

初期設定

使い方

実は