次の方法で共有

ヘルプ ファイルの変換と公開

この時点で、Markdown ヘルプ ファイルの作成、編集、テストが完了しているはずです。 次の手順では、Markdown ソース ファイルを MAML ヘルプ ファイルに変換し、モジュール用に公開します。

Markdown ファイルを MAML に変換する

次の例では、 .\WidgetModule ディレクトリに Markdown ヘルプ ファイルをインポートし、コマンド ヘルプを .\maml ディレクトリ内の MAML 形式にエクスポートします。

Measure-PlatyPSMarkdown -Path .\WidgetModule\*.md |
    Where-Object Filetype -match 'CommandHelp' |
    Import-MarkdownCommandHelp -Path {$_.FilePath} |
    Export-MamlCommandHelp -OutputFolder .\maml

ヘルプ ファイルを公開する

公開オプションには、次の 2 つがあります。

  • モジュールにヘルプファイルを含める
  • 更新可能なヘルプのヘルプ ファイルをパッケージ化する

オプション 1: モジュールにヘルプ ファイルを含める

Get-Help コマンドレットは、モジュール ディレクトリの言語固有のサブディレクトリにあるモジュール ヘルプ トピック ファイルを検索します。 MAML ヘルプ ファイルと about_*.help.txt ファイルをモジュール ディレクトリ内の言語固有のフォルダーにコピーします。 フォルダー名には、 en-US などのカルチャ コード形式を使用する必要があります。 たとえば、次のディレクトリ構造図は、WidgetModule モジュールのヘルプ トピックの場所を示しています。

<PSModulePath>/
└── WidgetModule/
    └── en-US/
        ├── about_WidgetModule.help.txt
        ├── WidgetModule-Help.xml
        └── NestedWidgetModule.dll-Help.xml

注

この例では、<PSModulePath>プレースホルダーは、$env:PSModulePath、$HOME\Documents\Modules、またはユーザーが指定したカスタムパスなど、$PSHOME\Modules環境変数内のパスの1つを表します。

他の言語でヘルプを作成した場合は、言語ごとに追加のフォルダを作成します。

オプション 2: 更新可能なヘルプのヘルプ ファイルをパッケージ化する

更新可能なヘルプをサポートするには、ヘルプ ファイル (MAML とテキスト ベースのヘルプの両方) をアーカイブ ファイルにパッケージ化し、ヘルプ コンテンツのダウンロード場所、ヘルプのバージョン、および使用可能な言語を含む HelpInfo.xml ファイルを作成する必要があります。

また、HTTPS をサポートする Web サーバーでヘルプ コンテンツをホストする必要があります。 モジュールにはモジュールマニフェストが必要です。 マニフェストの HelpInfoUri プロパティには、 HelpInfo.xml ファイルが配置されている Web サーバー上のフォルダーの場所への URL が含まれている必要があります。 この URL は、 HelpInfo.xml ファイルへのフルパスではなく、フォルダーの場所である必要があり、スラッシュ (/) 文字で終わる必要があります。

詳細については、「 更新可能なヘルプの作成」を参照してください。

PlatyPSは、このプロセスを容易にします。 モジュール Markdown ファイルの作成時にモジュール マニフェストに HelpInfoUri プロパティが含まれている場合、PlatyPS は必要なメタデータを Markdown ファイルに自動的に追加します。 次の例を使用して、更新可能なヘルプパッケージを作成します。

$params = @{
    CabinetFilesFolder = '.\maml\WidgetModule'
    MarkdownModuleFile = '.\WidgetModule\WidgetModule.md'
    OutputFolder       = '.\helppackage'
}
New-HelpCabinetFile @params

CabinetFilesFolder パラメーターは、パッケージに含める MAML およびテキストベースのヘルプ ファイルを含むフォルダーを指定します。 MarkdownModuleFile パラメーターは、HelpInfo.xml ファイルの作成に必要なメタデータを含むモジュール Markdown ファイルを指定します。 OutputFolder パラメーターは、.cab ファイルと.zipファイル、およびHelpInfo.xmlファイルが作成されるフォルダーを指定します。 これらのファイルを HelpInfoUri プロパティで指定された場所の Web サーバーにコピーします。

マニフェストの HelpInfoUri プロパティには、 HelpInfo.xml ファイルが配置されている Web サーバー上のフォルダーの場所への URL が含まれている必要があります。 Update-Help コマンドレットは、この場所を使用して、HelpInfo.xml ファイルへのフル パスを構築します。 Update-Help コマンドレットは、HelpInfo.xml ファイル内の情報を使用して、ヘルプ コンテンツ ファイルへのフル パスを作成します。

詳細については、「 更新可能なヘルプのしくみ」を参照してください。

  • Last updated on