Easily write PowerShell help files with platyPS

This article is a repost of an entry originally posted to Hatena Blog on 2019/02/08.

Introduction

There is a tool called platyPS provided by the PowerShell team.

https://github.com/PowerShell/platyPS

This tool loads existing modules to generate Markdown templates and can further read those Markdown files to generate PowerShell help files (dll-Help.xml). Since you can manage your documentation in Markdown format, it makes documenting much easier. Additionally, if you publish them to GitHub, they can be used directly as online documentation.

Creating Markdown Files

For example, suppose you have created the following cmdlet.

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()
        {
            // Serialize the message to JSON
            this.WriteObject(JsonConvert.SerializeObject(new { Message = "Hello World" }));
        }
    }
}

After importing the target module, you can call New-MarkdownHelp to generate a Markdown file for each cmdlet.

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

Generated Markdown files automatically contain information read from the module, but descriptions and similar content are not included. Please edit the sections enclosed in {{}}.

---
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

Creating Help Files

Once you have finished editing, specify the folder containing the Markdown files and call New-ExternalHelp to generate the help file.

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

That is all there is to it. Simple, right?

Reflecting Cmdlet Changes in Markdown

As you continue development, changes will occur in existing cmdlets. In such cases, calling Update-MarkdownHelp will update the differences.

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

After making modifications, regenerate the help file again using New-ExternalHelp. Note that if existing files already exist, they will not be overwritten, so don't forget to add the -Force parameter.