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
スクリプト(.ps1)
スクリプトの場合は、コメントベースヘルプ(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のサイトからの引用)。
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10"> <command:details> <!--Add name an synopsis here--> </command:details> <maml:description> <!--Add detailed description here--> </maml:description> <command:syntax> <!--Add syntax information here--> </command:syntax> <command:parameters> <!--Add parameter information here--> </command:parameters> <command:inputTypes> <!--Add input type information here--> </command:inputTypes> <command:returnValues> <!--Add return value information here--> </command:returnValues> <maml:alertSet> <!--Add Note information here--> </maml:alertSet> <command:examples> <!--Add cmdlet examples here--> </command:examples> <maml:relatedLinks> <!--Add links to related content here--> </maml:relatedLinks> </command:command>
とりあえず、参考になりそうなのは以下のサイト。よめば雰囲気でだいたいわかる。特に最後のSAPIEN社の公式ブログの「What do I name the XML help file?」はファイル命名規則について詳しく参考になる。
- How to Create the Cmdlet Help File
- Writing Help for Windows PowerShell Modules
- Writing XML Help for Advanced Functions - SAPIEN Information Center | SAPIEN Information Center
しかし、多言語対応するにはこのファイルを作ることが必要なのだが、残念なことにコマンドが自動でやってくれていた補完が効かない。 例えばParameterのattributeなど、コードで明示していることも、いちいち自分で書かないといけない。生のxmlを、しかも英語のレファレンスを見ながら書かざるを得ず、とてもつらい。
Git-Hubを見るとコードからヘルプ生成を自動化するプロジェクトも散見されるので、そのうち使って記事にしたいと思う。たとえばPowerShell/platyPSとか。
まとめ
ちゃんとGet-Help対応のヘルプ(Help Topic)を書こう。
