Powershellのスクリプト・モジュールで正しくGet-Helpで読むことができるヘルプトピック(Help topic)を作る方法のメモ。
そもそもヘルプトピックとは?
要するにGet-Help
したときに表示されるヘルプのこと*1。細かいことは詳しいヘルプ情報の取得 | Microsoft Docsを参照。
例えばGet-Help
コマンドレットをGet-Help
すると以下のようになる
PS D:\SandBox> get-help Get-ChildItem
名前
Get-ChildItem
概要
Gets the items and child items in one or more specified locations.
(以下略)
上記のようなヘルプトピックは、簡単にPowershellで自作したスクリプト・モジュールでも表示させることができるので、以降はその方法・記法を記載する*2
スクリプトの場合は、コメントベースヘルプ(Comment_Based_Help)をスクリプト内に記述することで、ヘルプトピックを作成できる。
記載場所は関数の宣言のすぐ上かすぐ下で、以下のようなイメージ。
.SYNOPSIS
.DESCRIPTION
.EXAMPLE
.EXAMPLE
.PARAMETER foo
.PARAMETER bar
function Do-Hoge {
(略)
}
関数の中に書く場合
function Do-Fuga {
.SYNOPSIS
.DESCRIPTION
.EXAMPLE
.EXAMPLE
.PARAMETER foo
.PARAMETER bar
(略)
}
もっと詳しいことはGet-Help about_Comment_Based_Help
を実行するか、以下のWebページを読むとわかると思う。
モジュール(.psm1)
モジュールの場合は、コメントベースヘルプも使えるが、それ以外にもヘルプを外部ファイルに記述して読み込ませることができる。
ファイルには、モジュール全体に対する説明である「概念説明のヘルプ(Conceptual ("About") Help)」と、個々の関数について記載する「コマンドレット ヘルプファイル(Cmdlet Help File)」の2種類がある。
なお、モジュールに関しては以下のブログ記事がとても参考になる。モジュールの自動読み込みについてとか。
モジュールヘルプの場所
以下のような形でヘルプファイルを配置すると、OSの言語によって自動的に読み込むヘルプファイルを切り替えてくれる。
<ModulePath>
\SampleModule
\<en-US>
\about_SampleModule.help.txt
\SampleModule.extention-help.xml
\SampleNestedModule.extention-help.xml
\<ja>
\about_SampleModule.help.txt
\SampleModule.extention-help.xml
\SampleNestedModule.extention-help.xml
このように多言語対応できるところが、この方式の強みだと思う。逆に言うと、Powershellでモジュールを書いて、かつドメスティックに使うだけならComment Basedで十分な気がする。
ロケール(en-USとか)の一覧はロケール ID (LCID) の一覧がVBScriptのレファレンスだが、参考になる。
概念説明のヘルプ(Conceptual ("About") Help)
モジュール全体の説明のことで、Writing Help for Windows PowerShell Modules.aspx)に詳しい。
以下のようなファイル(内容は上記サイトからの引用)を「about_hogehoge.help.txt」という名前で作ると、Get-Help about_hogehoge
で参照できる。
TOPIC
about_<subject or module name>
SHORT DESCRIPTION
A short, one-line description of the topic contents.
LONG DESCRIPTION
A detailed, full description of the subject or purpose of the module.
EXAMPLES
Examples of how to use the module or how the subject feature works in practice.
KEYWORDS
Terms or titles on which you might expect your users to search for the information in this topic.
SEE ALSO
Text-only references for further reading. Hyperlinks cannot work in the Windows PowerShell console.
コマンドレット ヘルプファイル(Cmdlet Help File)
モジュールの中のメンバー(関数など)のヘルプをxmlファイル(SampleModule.extention-help.xml)に記載する。
例としては以下のような感じ(MSのサイトからの引用)。
<commandcommand
xmlnsmaml="http://schemas.microsoft.com/maml/2004/10"
xmlnscommand="http://schemas.microsoft.com/maml/dev/command/2004/10"
xmlnsdev="http://schemas.microsoft.com/maml/dev/2004/10">
<commanddetails>
</commanddetails>
<mamldescription>
</mamldescription>
<commandsyntax>
</commandsyntax>
<commandparameters>
</commandparameters>
<commandinputTypes>
</commandinputTypes>
<commandreturnValues>
</commandreturnValues>
<mamlalertSet>
</mamlalertSet>
<commandexamples>
</commandexamples>
<mamlrelatedLinks>
</mamlrelatedLinks>
</commandcommand>
とりあえず、参考になりそうなのは以下のサイト。よめば雰囲気でだいたいわかる。特に最後のSAPIEN社の公式ブログの「What do I name the XML help file?」はファイル命名規則について詳しく参考になる。
しかし、多言語対応するにはこのファイルを作ることが必要なのだが、残念なことにコマンドが自動でやってくれていた補完が効かない。
例えばParameterのattributeなど、コードで明示していることも、いちいち自分で書かないといけない。生のxmlを、しかも英語のレファレンスを見ながら書かざるを得ず、とてもつらい。
Git-Hubを見るとコードからヘルプ生成を自動化するプロジェクトも散見されるので、そのうち使って記事にしたいと思う。たとえばPowerShell/platyPSとか。
まとめ
ちゃんとGet-Help
対応のヘルプ(Help Topic)を書こう。