PlatyPS を使用して XML ベースのヘルプを作成する

2024-12-13

PowerShell モジュールを作成するときは、作成するコマンドレットの詳細なヘルプを含める必要があります。コマンドレットがコンパイル済みコードに実装されている場合は、XML ベースのヘルプを使用する必要があります。この XML 形式は、Microsoft Assistance Markup Language (MAML) と呼ばれます。

従来の PowerShell SDK ドキュメントでは、モジュールにパッケージ化された PowerShell コマンドレットのヘルプの作成の詳細について説明します。ただし、PowerShell には、XML ベースのヘルプを作成するためのツールは用意されていません。 SDK ドキュメントでは MAML ヘルプの構造について説明していますが、複雑で深く入れ子になった MAML コンテンツを手動で作成する作業は残されています。

ここで、PlatyPS モジュールが役立ちます。

PlatyPS とは

PlatyPSは、MAMLの作成とメンテナンスを容易にするために、ハッカソン プロジェクトとして始まったオープンソースのツールです。 PlatyPS は、モジュール内の各コマンドレットのパラメーターセットと個々のパラメーターの構文を文書化します。 PlatyPS は、構文情報を含む Markdown ファイル構造化されたファイルを作成します。説明を作成したり、例を提供したりすることはできません。

PlatyPS では、説明と例を入力するためのプレースホルダーが作成されます。必要な情報を追加した後、PlatyPS は Markdown ファイルを MAML ファイルにコンパイルします。 PowerShell のヘルプシステムでは、プレーンテキストの概念ヘルプファイル (トピックについて) も使用できます。 PlatyPS には、ファイルに関する新しい用の構造化された Markdown テンプレートを作成するコマンドレットがありますが、これらのファイルは手動で管理する必要があります。

MAML ヘルプファイルとテキストヘルプファイルをモジュールに含めることができます。 PlatyPS を使用して、更新可能なヘルプ用にホストできる CAB パッケージにヘルプファイルをコンパイルすることもできます。

PlatyPS の使用を開始する

まず、PowerShell ギャラリーから PlatyPS をインストールする必要があります。

# Install using PowerShellGet 2.x
Install-Module platyps -Force

# Install using PSResourceGet 1.x
Install-PSResource platyps -Reinstall

PlatyPS をインストールした後、モジュールをセッションにインポートします。

Import-Module platyps

次のフローチャートは、PowerShell 参照コンテンツを作成または更新するプロセスの概要を示しています。

PlatyPS を使用して XML ベースのヘルプを作成するためのワークフロー

PowerShell モジュールの Markdown コンテンツを作成する

新しいモジュールをセッションにインポートします。文書化する必要があるモジュールごとに、この手順を繰り返します。

次のコマンドを実行してモジュールをインポートします。
```
Import-Module <your module name>
```
PlatyPS を使用して、モジュールページおよびモジュール内のすべての関連コマンドレットの Markdown ファイルを生成します。文書化する必要があるモジュールごとに、この手順を繰り返します。
```
$OutputFolder = <output path>
$parameters = @{
    Module = <ModuleName>
    OutputFolder = $OutputFolder
    AlphabeticParamsOrder = $true
    WithModulePage = $true
    ExcludeDontShow = $true
    Encoding = [System.Text.Encoding]::UTF8
}
New-MarkdownHelp @parameters

New-MarkdownAboutHelp -OutputFolder $OutputFolder -AboutName "topic_name"
```
出力フォルダーが存在しない場合は、New-MarkdownHelp 作成します。この例では、New-MarkdownHelp モジュール内のコマンドレットごとに Markdown ファイルを作成します。また、という名前のファイルにモジュールページも作成します。このモジュールページには、モジュールに含まれているコマンドレットの一覧と、Synopsis 説明のプレースホルダーが含まれています。モジュールページのメタデータはモジュールマニフェストから取得され、PlatyPS によって HelpInfo XML ファイルを作成するために使用されます (以下の説明します)。

New-MarkdownAboutHelp は、about_topic_name.mdという名前のファイルに関する新しい作成します。

詳細については、「New-MarkdownHelp と New-MarkdownAboutHelpのを参照してください。

モジュールが変更されたときに既存の Markdown コンテンツを更新する

PlatyPS では、モジュールの既存の Markdown ファイルを更新することもできます。新しいコマンドレット、新しいパラメーター、または変更されたパラメーターを持つ既存のモジュールを更新するには、この手順を使用します。

新しいモジュールをセッションにインポートします。文書化する必要があるモジュールごとに、この手順を繰り返します。

次のコマンドを実行してモジュールをインポートします。
```
Import-Module <your module name>
```
PlatyPS を使用して、モジュールのランディングページの Markdown ファイルと、モジュール内のすべての関連コマンドレットを更新します。文書化する必要があるモジュールごとに、この手順を繰り返します。
```
$parameters = @{
    Path = <folder with Markdown>
    RefreshModulePage = $true
    AlphabeticParamsOrder = $true
    UpdateInputOutput = $true
    ExcludeDontShow = $true
    LogPath = <path to store log file>
    Encoding = [System.Text.Encoding]::UTF8
}
Update-MarkdownHelpModule @parameters
```
Update-MarkdownHelpModule は、指定したフォルダー内のコマンドレットとモジュールの Markdown ファイルを更新します。 about_*.md ファイルは更新されません。モジュールファイル (ModuleName.md) は、コマンドレットファイルに追加された新しい Synopsis テキストを受け取ります。コマンドレットファイルの更新には、次の変更が含まれます。
- 新しいパラメーターセット
- 新しいパラメーター
- パラメーターメタデータの更新
- 入力と出力の種類の情報を更新しました
詳細については、「Update-MarkdownHelpModuleをする」を参照してください。

新規または更新された Markdown ファイルを編集する

PlatyPS では、パラメーターセットの構文と個々のパラメーターが文書化されています。説明を作成したり、例を提供したりすることはできません。コンテンツが必要な特定の領域は、中かっこに含まれています。例: {{ Fill in the Description }}

VS Code のプレースホルダーを示す Markdown テンプレートをする

概要、コマンドレットの説明、各パラメーターの説明、および少なくとも 1 つの例を追加する必要があります。

PowerShell コンテンツの記述の詳細については、次の記事を参照してください。

手記

PlatyPS には、コマンドレット参照に使用される特定のスキーマがあります。このスキーマでは、ドキュメントの特定のセクション内の特定の Markdown ブロックのみが許可されます。コンテンツを間違った場所に配置すると、PlatyPS ビルドステップは失敗します。詳細については、PlatyPS リポジトリのスキーマドキュメントを参照してください。整形式コマンドレットリファレンスの完全な例については、「Get-Item参照してください。

各コマンドレットに必要なコンテンツを提供したら、モジュールのランディングページを更新する必要があります。モジュールが、<module-name>.md ファイルの YAML メタデータに正しい Module Guid と Download Help Link 値があることを確認します。不足しているメタデータを追加します。

また、一部のコマンドレットに Synopsis (簡単な説明) がない場合があります。次のコマンドは、モジュールのランディングページを Synopsis 説明テキストで更新します。モジュールのランディングページを開き、説明を確認します。

Update-MarkdownHelpModule -Path <full path output folder> -RefreshModulePage

すべてのコンテンツを入力したら、PowerShell コンソールで Get-Help 表示される MAML ヘルプファイルを作成できます。

外部ヘルプファイルを作成する

この手順では、PowerShell コンソールで Get-Help によって表示される MAML ヘルプファイルを作成します。

MAML ファイルをビルドするには、次のコマンドを実行します。

New-ExternalHelp -Path <folder with MDs> -OutputPath <output help folder>

New-ExternalHelp は、すべてのコマンドレット Markdown ファイルを 1 つ以上の MAML ファイルに変換します。 About ファイルは、次の名前形式のプレーンテキストファイルに変換されます: about_topic_name.help.txt. Markdown コンテンツは、PlatyPS スキーマの要件を満たしている必要があります。コンテンツがスキーマに従っていない場合、New-ExternalHelp はエラーで終了します。スキーマ違反を修正するには、ファイルを編集する必要があります。

注意

PlatyPS は、about_*.md ファイルをプレーンテキストに変換する処理が不適切です。受け入れ可能な結果を得るには、非常に単純な Markdown を使用する必要があります。 PlatyPS でファイルを変換するのではなく、プレーンテキスト about_topic_name.help.txt 形式でファイルを保持できます。

この手順が完了すると、ターゲット出力フォルダーに *-help.xml ファイルと about_*.help.txt ファイルが表示されます。

詳細については、「New-ExternalHelp のを参照してください。

コンパイル済みのヘルプファイルをテストする

Get-HelpPreview コマンドレットを使用してコンテンツを確認できます。

Get-HelpPreview -Path "<ModuleName>-Help.xml"

このコマンドレットは、コンパイル済みの MAML ファイルを読み取り、Get-Helpから受け取るのと同じ形式でコンテンツを出力します。これにより、結果を調べて、Markdown ファイルが正しくコンパイルされたことを確認し、目的の結果を生成できます。エラーが発生した場合は、Markdown ファイルを再編集し、MAML を再コンパイルします。

これで、ヘルプファイルを発行する準備ができました。

ヘルプの公開

これで、Markdown ファイルを PowerShell ヘルプファイルにコンパイルできました。これで、ユーザーがファイルを使用できるようになります。 PowerShell コンソールでヘルプを提供するには、2 つのオプションがあります。

モジュールを使用してヘルプファイルをパッケージ化する
Update-Help コマンドレットを使用してユーザーがインストールする更新可能なヘルプパッケージを作成する

モジュールのパッケージ化のヘルプ

ヘルプファイルはモジュールと共にパッケージ化できます。フォルダー構造の詳細については、モジュールの書き込みヘルプを参照してください。モジュールマニフェストの FileList キーの値にヘルプファイルの一覧を含める必要があります。

更新可能なヘルプパッケージの作成

大まかに言うと、更新可能なヘルプを作成する手順は次のとおりです。

ヘルプファイルをホストするインターネットサイトを見つける
HelpInfoURI キーをモジュールマニフェストに追加する
HelpInfo XML ファイルを作成する
CAB ファイルを作成する
ファイルをアップロードする

詳細については、「更新可能なヘルプのサポート : ステップバイステップ」を参照してください。

PlatyPS は、これらの手順の一部を支援します。

HelpInfoURI は、ヘルプファイルがインターネット上でホストされている場所を指す URL です。この値はモジュールマニフェストで構成されます。 Update-Help モジュールマニフェストを読み取ってこの URL を取得し、更新可能なヘルプコンテンツをダウンロードします。この URL は、個々のファイルではなく、フォルダーの場所のみを指す必要があります。 Update-Help は、モジュールマニフェストと HelpInfo XML ファイルの他の情報に基づいて、ダウンロードするファイル名を構築します。

大事な

HelpInfoURI は、スラッシュ (/) で終わる必要があります。その文字がないと、Update-Help はコンテンツをダウンロードするための正しいファイルパスを構築できません。また、ほとんどの HTTP ベースのファイルサービスでは大文字と小文字が区別されます。 HelpInfo XML ファイルのモジュールメタデータに適切な文字ケースが含まれていることが重要です。

New-ExternalHelp コマンドレットは、出力フォルダーに HelpInfo XML ファイルを作成します。 HelpInfo XML ファイルは、モジュール Markdown ファイル (ModuleName.md) に含まれる YAML メタデータを使用して構築されます。

New-ExternalHelpCab コマンドレットは、コンパイルした MAML ファイルと about_*.help.txt ファイルを含む ZIP ファイルと CAB ファイルを作成します。 CAB ファイルは、PowerShell のすべてのバージョンと互換性があります。 PowerShell 6 以降では、ZIP ファイルを使用できます。

$helpCabParameters = @{
    CabFilesFolder = $MamlOutputFolder
    LandingPagePath = $LandingPage
    OutputFolder = $CabOutputFolder
}
New-ExternalHelpCab @helpCabParameters

ZIP ファイルと CAB ファイルを作成したら、ZIP、CAB、HelpInfo XML ファイルを HTTP ファイルサーバーにアップロードします。 HelpInfoURIで示される場所にファイルを配置します。

詳細については、「New-ExternalHelpCabを参照してください。

その他の発行オプション

Markdown は、発行のために他の形式に簡単に変換できる汎用性の高い形式です。 Pandocなどのツールを使用すると、Markdown ヘルプファイルを、プレーンテキスト、HTML、PDF、Office ドキュメント形式など、さまざまなドキュメント形式に変換できます。

また、PowerShell 6 以降の ConvertFrom-Markdown と Show-Markdown コマンドレットを使用して、Markdown を HTML に変換したり、PowerShell コンソールでカラフルなディスプレイを作成したりできます。

既知の問題

PlatyPS は、作成およびコンパイルする Markdown ファイルの構造のスキーマに非常に敏感です。このスキーマに違反する有効な Markdown を非常に簡単に記述できます。詳細については、PowerShell スタイルガイドのおよび編集に関するリファレンス記事を参照してください。