Meet The New Platyps
In this issue:
For many years I have been using the Platyps module from Microsoft to build and manage the help documentation for my PowerShell modules. The workflow is very straightforward. Create an interim Markdown document based on the command. Then create external MAML help in the form of an XML file from the set of Markdown documents. I've even created PowerShell tools to streamline the process.
Recently, Microsoft has released a rewritten and restructured version of Platyps. The old version, 0.14.2, is still in the PowerShell Gallery. But I don't expect that version to see any updates. Instead we will begin using the Microsoft.PowerShell.Platyps module.
PS C:\> Find-PSResource Microsoft.PowerShell.Platyps
Name Version Prerelease Repository Description
---- ------- ---------- ---------- -----------
Microsoft.PowerShell.PlatyPS 1.0.3 PSGallery Generate PowerShell External Help files …
This is an open source project you can find on GitHub. The module runs on both Windows PowerShell 5.1 and PowerShell 7, including cross-platform. I've started the process of migrating to the new model and thought more than a few of you will also want to make the journey. You can find the official documentation at https://learn.microsoft.com/powershell/utility-modules/platyps/overview. I'll be sharing my experiences and code around the migration process.
After you install the module you should run Update-Help. Unfortunately, even then some of the Platyps commands might be missing help content.
Module Commands
The module has a new paradigm. You create a new command help object which can then be saved in Markdown, Yaml, or Maml. If you need the traditional Maml XML file, you can export the source documents. I suppose the idea is that the module gives you more granular control and options.
PS C:\> Get-Command -module Microsoft.PowerShell.PlatyPS | Select Name
Name
----
New-HelpCabinetFile
Show-HelpPreview
Compare-CommandHelp
Export-MamlCommandHelp
Export-MarkdownCommandHelp
Export-MarkdownModuleFile
Export-YamlCommandHelp
Export-YamlModuleFile
Import-MamlHelp
Import-MarkdownCommandHelp
Import-MarkdownModuleFile
Import-YamlCommandHelp
Import-YamlModuleFile
Measure-PlatyPSMarkdown
New-CommandHelp
New-MarkdownCommandHelp
New-MarkdownModuleFile
Test-MarkdownCommandHelp
Update-CommandHelp
Update-MarkdownCommandHelp
Update-MarkdownModuleFile
I'm not going to cover every command.
Start with a Command
Let's begin with a stand-alone function.
function Get-OSInfo {
[cmdletbinding()]
[OutputType('OperatingSystemInfo')]
param(
[Parameter(Position = 0, ValueFromPipeline, HelpMessage = "Specify the name of a computer to query.")]
[Alias('cn')]
[ValidateNotNullOrEmpty()]
[string[]]$Computername = $env:computername,
[Parameter(HelpMessage = "Return the OS name only.")]
[switch]$NameOnly
)
begin {
Write-Verbose "[BEGIN ] Starting: $($MyInvocation.MyCommand)"
$paramHash = @{
ClassName = 'Win32_OperatingSystem'
ErrorAction = 'Stop'
}
} #begin
process {
foreach ($computer in $Computername) {
Write-Verbose "[PROCESS] Connecting to $Computer"
$paramHash.Computername = $Computer
try {
$data = Get-CimInstance @paramHash
if ($NameOnly) {
$data.caption
}
else {
[PSCustomObject]@{
PSTypename = 'OperatingSystemInfo'
Name = $data.Caption
Version = $data.Version
Architecture = $data.OSArchitecture
InstallDate = $data.InstallDate
Computername = $data.CSName
}
}
} #try
catch {
Write-Warning "Failed to retrieve information from $($computer.ToUpper()). $($_.Exception.Message)"
} #catch
} #Foreach
} #process
end {
Write-Verbose "[END ] Ending: $($MyInvocation.MyCommand)"
} #end
}
Once this function is loaded into my PowerShell session, I'll begin the documentation process by creating a help object.
> The output you would see is slightly different than what I'm showing here. I've had to tweak some of the Markdown syntax to avoid rendering problems in the newsletter.
PS C:\> $h = Get-Command Get-OSInfo | New-CommandHelp
PS C:\> $h
Title ModuleName Synopsis
----- ---------- --------
Get-OSInfo { Fill in the Synopsis }
Updating the Help Object
One benefit with this approach is that you can edit the help programmatically by updating the object.
PS C:\> $h | Select *
Metadata : {[document type, cmdlet], [title, Get-OSInfo], [Module Name, ], [Lo…}
Locale : en-US
ModuleGuid :
ExternalHelpFile : Get-OSInfo-Help.xml
OnlineVersionUrl :
SchemaVersion : 2024-05-01
ModuleName :
Title : Get-OSInfo
Synopsis : {Fill in the Synopsis }
Syntax : {Get-OSInfo [[-Computername] <string[]>] [-NameOnly]}
AliasHeaderFound : False
Aliases :
Description : { Fill in the Description }
Examples : {Microsoft.PowerShell.PlatyPS.Model.Example}
Parameters : {Computername, NameOnly}
Inputs : {System.String[]}
Outputs : {OperatingSystemInfo}
Notes : { Fill in the Notes }
RelatedLinks : {}
HasCmdletBinding : True
HasWorkflowCommonParameters : False
Diagnostics : Microsoft.PowerShell.PlatyPS.Model.Diagnostics
I'm assuming the property names look familiar to you from the legacy Platyps Markdown documents. I can update the "help" directly from the command line.
$h.synopsis = "Get operating system information"
$h.Description = "This command uses Get-CimInstance to query one or more remote computers to gather a summary of operating system information. You can also opt to return the operating system name only."
But you have to be careful. Some properties aren't what you might expect.
PS C:\> $h.Examples
Title Remarks
----- -------
Example 1 { Add example description here }
PS C:\> $h.Examples.Remarks = "Get-OSInfo"
InvalidOperation: The property 'Remarks' cannot be found on this object. Verify that the property exists and can be set.
PS C:\>
