Generating PowerShell module documentation with platyPS

Creating accurate and efficient documentation is paramount in technical writing, especially for PowerShell modules. platyPS, an open-source module, emerged as a solution for generating Markdown-based reference content for PowerShell modules. This article provides a comprehensive guide for using platyPS to create and maintain high-quality reference documentation for your PowerShell module, enhancing the experience for both module authors and users.

What is platyPS

platyPS (pronounced "platypus") started as a tool to convert PowerShell help files into Markdown format. Over time, it evolved into a powerful tool for generating and maintaining PowerShell module documentation directly from the source code and inline documentation. This streamlines the process, ensuring consistency and accuracy while saving valuable time.

A platypus generating PowerShell module documentation

Prerequisites

Before diving into platyPS, ensure you have PowerShell installed. For more information, see Install PowerShell on Windows, Linux, and macOS. Most platyPS commands are cross-platform and work on all platforms supported by PowerShell.

Installation

Install platyPS from the PowerShell Gallery.

1Install-Module -Name platyPS

Installing platyPS

Define variables

Store the PowerShell module name to document and the locations for the output of the help content in variables. You'll use these variables throughout this article.

1$moduleName = 'MrInspector'
2$markdownPath = '.\docs'
3$mamlPath = '.\en-US'

Define variables

Generating Markdown files

  1. Import the module to document: Import the module you want to document into your PowerShell session.

    1Import-Module -Name $moduleName
    

    Importing the module you want to document

  2. Generate initial Markdown help: Run New-MarkdownHelp to create a set of Markdown files for your module. The following parameters are specified in the example below:

    • Module: The name of the module to document.
    • OutputFolder: The folder where you want the generated Markdown files saved.
    • AlphabeticParamsOrder: Sorts parameters in the PARAMETERS section alphabetically except for common parameters and a few other exceptions. This makes finding parameters easier and merging changes less painful.
    • UseFullTypeName: Use full type names for parameter types.
    • WithModulePage: Create a module-level help file.
    • ExcludeDontShow: Include parameters with the DontShow attribute in the generated help because the value is set to true.
    • Encoding: Generate the Markdown files using UTF-8 encoding.
     1$mdHelpParams = @{
     2     Module                = $moduleName
     3     OutputFolder          = $markdownPath
     4     AlphabeticParamsOrder = $true
     5     UseFullTypeName       = $true
     6     WithModulePage        = $true
     7     ExcludeDontShow       = $false
     8     Encoding              = [System.Text.Encoding]::UTF8
     9 }
    10 New-MarkdownHelp @mdHelpParams
    

    Creating Markdown help

  3. Inspect the files created: platyPS creates one Markdown file for each cmdlet in the module, plus a module-level help file.

  4. Edit the Markdown files: The generated files contain boilerplate text and prompts to fill in details. Edit these files to add parameter descriptions, examples, and other relevant information.

Updating Markdown files

Use Update-MarkdownHelp to keep your Markdown files in sync as your module evolves. The following example updates all Markdown files in the $markdownPath folder.

1Update-MarkdownHelp -Path $markdownPath

Updating Markdown help

Tip: To avoid overwriting modifications you've made to the Markdown files, consider using New-MarkdownHelp to generate new versions in a different folder instead of using Update-MarkdownHelp, then merge the changes with a comparison tool such as Beyond Compare.

Create about help topics

Use New-MarkdownHelpAbout to create optional about-help topics for your module.

1New-MarkdownAboutHelp -OutputFolder $markdownPath -AboutName $moduleName

Creating about help topics

Creating external help

After editing the Markdown files, use platyPS to generate external help files in a special XML format known as Microsoft Assistance Markup Language (MAML), which PowerShell can use as cmdlet help.

  1. Generate MAML: Use New-ExternalHelp to create MAML help files.

    1   $extHelpParams = @{
    2       Path = $markdownPath
    3       OutputPath = $mamlPath
    4   }
    5   New-ExternalHelp @extHelpParams
    

    Generating external help

  2. Preview the MAML content: Use Get-HelpPreview to test the generated MAML help content and ensure it renders correctly.

    1Get-HelpPreview -Path "$mamlPath\$moduleName-help.xml"
    

    Testing the MAML

Publish the help content

Depending on your requirements, you can publish the help content in several ways.

Ship external help with your module

Include the MAML and about-help topic files with your module to provide integrated help for users of your module. Get-Help looks for module help topic files in language-specific subfolders of your module. The folder structure diagram in the following example shows the location of help topics for my MrInspector PowerShell module.

1<Location in $env:PSModulePath>
2└── MrInspector
3      └── 0.1.0
4         └── en-US
5            ├── MrInspector-help.xml
6            └── about_MrInspector.help.txt

Folder structure of a module with external help

Updatable help

Note: New-ExternalHelpCab is only supported on Windows because it relies on makecab.exe to create CAB files.

  1. Generate files for updatable help: Use New-ExternalHelpCab to create the module help CAB, ZIP, and HelpInfo XML files.

    1$extHelpCabParams = @{
    2    CabFilesFolder = $mamlPath
    3    LandingPagePath = "$markdownPath/$moduleName.md"
    4    OutputFolder = "$mamlPath/cab"
    5}
    6New-ExternalHelpCab @extHelpCabParams
    

    Creating module help CAB, ZIP, and HelpInfo XML files

  2. Publish files for updatable help: Publish the CAB/XML files to a web server where your users can access them.

  3. Point the HelpInfoURI property of your module manifest to the folder location of the HelpInfo XML file on the web server. This URL must only point to the folder location, not to the individual file, and it must end with a forward-slash character (/).

Best practices

  • Regular updates: Regularly update your documentation to reflect changes in your module.
  • Version control: Store your documentation in a version control system alongside your module code. This facilitates tracking changes and collaborating with others.
  • Peer review: Have your documentation reviewed by peers for accuracy and clarity.
  • User feedback: Incorporate feedback to improve the usefulness and readability of the documentation.
  • Automation: Automate the generation and updating of documentation as part of the development lifecycle of your module.
  • Consistency: Maintain a consistent style and format across your documentation for a professional look and feel.

Summary

platyPS is an indispensable tool for any PowerShell module author. It automates the generation and maintenance of documentation based on Markdown, ensuring accuracy and consistency and significantly streamlining the process. As PowerShell continues to be an essential tool for system administrators and developers, effective documentation created with tools like platyPS remains crucial for any high-quality PowerShell module.

References

Acknowledgments

Thanks to Sean Wheeler for sharing his insight into this topic and providing valuable feedback that improved the quality of this article.