Module Documentation with Microsoft.PowerShell.Platyps
In this issue:
We've been exploring the new Platyps module from Microsoft that replaces the now legacy Platyps module. You should begin transitioning to Microsoft.PowerShell.Platyps, which is why I've been writing about it. Today, let's look at how you can use the module to create help documentation for your PowerShell modules. We'll use the same concepts and techniques I showed you in the previous newsletters.
Today, I want to focus on creating new help documents. Eventually, we will look at the migration process for existing modules.
Modules
Conceptually, the workflow is not that much different than what we did with the previous Platyps module. The goal is to create a MAML-based XML file for the module. I suppose it is possible with the new module that you could create the XML file from the module commands without creating any intermediary Markdown files, but I think this would require extensive scripting. I think it is just as easy to create the Markdown files first, update them, and then export them to MAML. Plus, you can use the Markdown documents as online help resources.
My recommendation is to create a folder called docs in your module to hold the Markdown documents. The MAML file needs to go into a culture-specific folder like en-US. Here's the layout of the module I'm going to be working with.
+--docs
+--en-US
+--formats
| +--lxService.format.ps1xml
| \--lxtools.format.ps1xml
+--functions
| +--Get-LxDiskInfo.ps1
| +--Get-LxIPInfo.ps1
| +--Get-LxMemoryInfo.ps1
| +--Get-LxOSInfo.ps1
| +--Get-LxService.ps1
| +--Get-LxStatus.ps1
| +--Get-LxTcpInfo.ps1
| +--Get-LxTools.ps1
| +--Get-LxTotalDiskSize.ps1
| +--Get-LxTotalMemory.ps1
| \--Get-LxUptime.ps1
+--images
| \--Tux.png
+--types
+--.markdownlint.json
+--CHANGELOG.md
+--PSLinuxTools.psd1
+--PSLinuxTools.psm1
Building New Command Help
This is a new module with no existing Markdown help files. I need to create Markdown help for every command. I demonstrated this process before.
Get-Command -module PSLinuxTools -commandType Function | New-MarkdownCommandHelp -OutputFolder .\docs\ -AbbreviateParameterTypeName -Force
Even though Get-Command in PowerShell 7 should only list functions, I want to be explicit so that I don't try to run New-MarkdownCommandHelp on aliases.
However, we still run into the path quirk. I am running this command in the module root. This will create a Markdown help document for every command, but not in the docs folder, but rather docs\PSLinuxTools.
I'll need to use a bit of code to get things where I want them.
#use temp folder and move to docs
#run from the module root
Import-Module .\PSLinuxTools.psd1 -Force
$files = Get-Command -module PSLinuxTools -CommandType Function |
New-MarkdownCommandHelp -OutputFolder $env:TEMP -AbbreviateParameterTypeName -Force
if (-Not (Test-Path .\docs)) {
#create the docs folder
New-Item -Name docs -Path . -ItemType Directory
}
$files | Move-Item -Destination .\docs
Now I can edit the Markdown files. If your script file had comment-based help, it will be incorporated into the Markdown file. You can delete the comment-based help from the scripts. In the Markdown files, I will insert code fencing and use other inline code highlighting because these files will eventually be online help documents in GitHub. I'll strip off the Markdown when I create the external help later.
Inline Updating
Another option is to take advantage of the help command object and update it before committing it to a Markdown file. For example, I like to insert a pointer to the newsletter in the Notes section. I can update the Notes property of each object.
$item.Notes = "Learn more about PowerShell: http://jdhitsolutions.com/yourls/newsletter"
I can also do things like insert a code fence into my examples and remove placeholders. I can even overcome the bug with aliases and handle that myself. Here's code that I can run to create the help objects, update them, convert to Markdown and save the files to the specified folder. This gets me around the path issue as well.
Import-Module .\PSLinuxTools.psd1 -Force
$ch = Get-Command -module PSLinuxTools -CommandType Function | New-CommandHelp
$fence = $([string]"``")*3
foreach ($item in $ch) {
$item.Notes = "Learn more about PowerShell: http://jdhitsolutions.com/yourls/newsletter"
#update examples
$remarks = @"
$($fence)powershell
PS C:\> $($item.Syntax[0].CommandName)
$fence
"@
if ($item.Examples) {
$item.Examples[0].Remarks = $remarks
}
else {
$ex = [Microsoft.PowerShell.PlatyPS.Model.Example]::new("Example 1",[System.String]$remarks)
$item.Examples.Add($ex)
}
#insert Alias information
#ignore errors when no alias is defined
$cmdAliases = (Get-Alias -Definition $($item.Title) -ErrorAction SilentlyContinue).name
if ($cmdAliases) {
$item.Aliases = @"
This command has the following aliases:
$($cmdAliases.foreach({"`r- {0}" -f "``$_``"}))
"@
}
Else {
$item.Aliases = $null
}
#create the markdown files in the correct location
$out = Join-Path -path C:\temp\PSLinuxTools\docs -ChildPath "$($item.Title).md"
#clear Fill in placeholders
# I am escaping the brackets to avoid a problem publishing
# this online. The escapes aren't really necessary.
$md = $item.ToMarkdownString() -replace '\{\{ Fill in the related links here \}\}',""
$md = $md -replace '\{\{ Fill in the Description \}\}',""
$md.TrimEnd() | Out-File -FilePath $out
}
For the sake of demonstration, my code is creating the Markdown files in C:\temp so that I don't overwrite the files I've already created. I would turn this code into a parameterized script file that would detect the module name.
