📝

platyPS で PowerShell ヘルプ ファイルを簡単に書く

に公開
C#
PowerShell
tech

はじめに

PowerShell チームから提供されている platyPS というツールがあります。

https://github.com/PowerShell/platyPS

既存のモジュールを読み込んで Markdown 形式のテンプレートを生成し、さらに Markdown ファイルを読み込んで PowerShell ヘルプ ファイル (dll-Help.xml) を生成してくれるツールです。ドキュメントを Markdown 形式で管理できるため、ドキュメントの記述が容易になります。また、GitHub に公開しておけばそのままオンライン ドキュメントとしても利用できます。

Markdown ファイルを作成する

例えば、次のようなコマンドレットを作成したとします。

using Newtonsoft.Json;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Management.Automation;
using System.Text;

namespace SampleModule
{
    [Cmdlet("Write", "HelloWorld")]
    public class WriteHelloWorldCommand : PSCmdlet
    {
        protected override void ProcessRecord()
        {
            this.WriteObject(JsonConvert.SerializeObject(new { Message = "Hello World" }));
        }
    }
}

対象のモジュールをインポートしてから New-MarkdownHelp を呼び出すと、コマンドレットごとに Markdown ファイルを生成できます。

Import-Module -Name ".\bin\Debug\SampleModule.psd1"
New-MarkdownHelp -Module "SampleModule" -OutputFolder ".\documents\"

生成された Markdown ファイルには、モジュールから読み取った情報が自動的に埋め込まれていますが、説明などは含まれていません。{{}} で囲まれている箇所について修正してください。

---
external help file: SampleModule.dll-Help.xml
Module Name: SampleModule
online version:
schema: 2.0.0
---

# Write-HelloWorld

## SYNOPSIS
{{Fill in the Synopsis}}

## SYNTAX

```
Write-HelloWorld [<CommonParameters>]
```

## DESCRIPTION
{{Fill in the Description}}

## EXAMPLES

### Example 1
```powershell
PS C:\> {{ Add example code here }}
```

{{ Add example description here }}

## PARAMETERS

### CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable.
For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216).

## INPUTS

### None

## OUTPUTS

### System.Object
## NOTES

## RELATED LINKS

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

修正が終わったら Markdown ファイルのあるフォルダーを指定して New-ExternalHelp を呼び出してヘルプ ファイルを生成します。

New-ExternalHelp -Path ".\documents\" -OutputPath ".\bin\Debug\SampleModule.dll-Help.xml"

これだけです。簡単ですね。

コマンドレットの変更を Markdown に反映する

開発を進めていくと、既存のコマンドレットに変更が発生します。そのような場合は Update-MarkdownHelp を呼び出すと差分を更新してくれます。

Import-Module -Name ".\bin\Debug\SampleModule.psd1"
Update-MarkdownHelp -Path ".\documents\"

修正したらまた New-ExternalHelp でヘルプ ファイルを再生成します。なお既存のファイルが存在すると上書きされないので Force を付けるのを忘れずにしてください。

Discussion