Zenn
📝

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

2022/01/01に公開
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 を呼び出すといい感じに差分を更新してくれます。[1]

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

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

脚注

  1. New-MarkdownHelp と Update-MarkdownHelp で微妙にパラメーターが違うので注意。どうしてこうなった。 ↩︎

Discussion