PowerShell MAML ヘルプ ジェネレーター
-
23-09-2019 - |
質問
PowerShell コマンドレットのヘルプ ファイルを生成するユーティリティを知っている人はいますか?手作業でやるのはちょっと面倒な気がしますが…
私が見つけた: http://blogs.msdn.com/powershell/archive/2007/09/01/new-and-improved-cmdlet-help-editor-tool.aspx
更新されたバージョンはありますか?モジュールを選択できません。バイナリモジュールがあります。
他のヒント
私は自分のモジュールを文書化しなければならなかったし、私自身のMAMLヘルプビルダーを作成するよりも、任意のより良い解決策を見つけることができませんでした。ここにあります: https://github.com/nightroman/Helpsする
モジュールは、PowerShellのヘルプスクリプトからPowerShellのMAMLのヘルプファイルを作成します。 ヘルプスクリプトは、結果のヘルプと非常に似て、ほとんどWYSIWYGです。 それでも、彼らはただのスクリプトがあり、これは容易な便利な機能の多くを作ります。 そのうちの一つは、いくつかの文化のためのヘルプファイルを構築しています。
ここでコマンドのヘルプデータのテンプレートがある(コマンドレット、関数、スクリプト)とプロバイダーます:
### Command help data
@{
command = 'Name'
synopsis = '...'
description = '...'
sets = @{
Set1 = '...'
#...
}
parameters = @{
Param1 = '...'
#...
}
inputs = @(
@{
type = '...'
description = '...'
}
#...
)
outputs = @(
@{
type = '...'
description = '...'
}
#...
)
notes = '...'
examples = @(
@{
title = '...'
introduction = '...'
code = {
}
remarks = '...'
test = {
. $args[0]
}
}
#...
)
links = @(
@{
text = '...'
URI = '...'
}
#...
)
}
### Provider help data
@{
provider = 'Name'
drives = '...'
synopsis = '...'
description = '...'
capabilities = '...'
tasks = @(
@{
title = '...'
description = '...'
examples = @(
@{
title = '...'
introduction = '...'
code = {
}
remarks = '...'
test = {
. $args[0]
}
}
)
}
#...
)
parameters = @(
@{
name = '...'
type = '...'
description = '...'
cmdlets = '...'
values = @(
@{
value = '...'
description = '...'
}
#...
)
}
#...
)
notes = '...'
links = @(
@{
text = '...'
URI = '...'
}
#...
)
}
私はスナップイン/モジュールのC#コードに埋め込むドキュメントへの道を見てきたし、 PoshBuildする私の最良の選択肢のように見えるし始めています。これは、ドキュメントの要素(例えば、概要および例)の一部を含める方法を提供していませんが、それはまだ良いオプションです。
XML PowerShell ヘルプ (PSMAML) を編集するためのグラフィカル ツールに関しては、以下を使用できます。
- PowerShell コマンドレット ヘルプ エディター (オープン ソース、コマンドレット ヘルプ エディターの精神的な後継者のようなもの)。
- PowerShell ヘルプライター (コマーシャル)。
オープンソースの出現により、 XmlDoc2CmdletDoc, を文書化できるようになりました。 バイナリ PowerShell コマンドレット (つまり、C# で書かれたもの)他の C# ライブラリと同様に、 スクリプト化された コマンドレット (PowerShell で記述されたコマンドレット):インラインドキュメントコメントを使用します。
並行性を維持する必要はもうありません MAML 手作業でファイルする!ビルドをインストルメント化するだけで、C# プロジェクトを再コンパイルするときにドキュメント ジェネレーターが実行され、両方の モジュール.dll そして モジュール.dll-ヘルプ.xml. 。後者は、コマンドレットを呼び出すときにコマンドレットに関するヘルプを提供するために PowerShell によって直接使用されます。 Get-Help
.
そして、XmlDoc2CmdletDoc は、 -strict
コマンドレットを包括的に文書化していることを確認するために切り替えてください。スイッチを使用していて何かを見逃した場合、ビルドは当然失敗します。
XmlDoc2CmdletDoc によって自動的に提供されるその他の利点 (このリストの「セクション」とは、XmlDoc2CmdletDoc によって提供されるヘルプのセクションを指します) Get-Help
):
- の各カスタム タイプ 出力 セクションに説明が含まれています。
- の 構文 このセクションには、列挙型の可能な値が含まれています。
- の パラメータ このセクションには、列挙型の可能な値が含まれています。
- エイリアスは自動的に文書化されます。 パラメーター セクション。
- エイリアスはファーストクラスのパラメータとして扱われるため、エイリアスについてヘルプを求めることができます。
- オプションで、パラメータに別の説明を使用できます。 入力 セクションと同様に、 パラメータ セクション。
- Web リンクは、ライブ リンクへの後処理を可能にするために、マークダウン形式で自動的にレンダリングされます。(この機能強化は保留中です。)
私はこのオープンソース ユーティリティがとても気に入ったので、上記の利点のいくつかを提供するために貢献し始めました。そして、私はそれを使用するための包括的なガイドを書きました。 PowerShell バイナリ コマンドレットの文書化, 、Simple-Talk.com で公開されました。