Generating A Simple Markdown Readme From Powershell Comments

Some of the powershell functions and modules I write don’t warrant elaborate commenting. I’ve started using a standard commenting template and rather than re-do that commenting in markdown, I eventually wrote a simple script to generate markdown out of powershell comments.

I work in an environment that uses a central git repository so simple generation of a README.md is an easy win. There’s a free module for generating markdown called platyPS but it’s a bit overkill for my lowly DBA needs. platyPS generates 1 markdown file per function. Our git repo can only display 1 README.md per folder, so having 1 markdown file that covers multiple functions is useful.

We’ll generate a README.md off the comments within my Oz.psm1 module which is defined as follows:

function New-Witch {
<# .NOTES NAME: New-Witch AUTHOR: James Livingston CREATED: 1939 .SYNOPSIS Creates a new wicked witch. #>
'Hello, my pretty!'
}
function Remove-Witch {
<# .NOTES NAME: Remove-Witch AUTHOR: James Livingston CREATED: 1939 .SYNOPSIS Function to kill the wicked witch. #>
'Ohhh, what a world!'
}

Specify the module to read and the output markdown file.

<# .NOTES NAME: Generate-Markdown.ps1 AUTHOR: James Livingston CREATED: 1/16/2017 .SYNOPSIS Reads the comments of a powershell module and generates a single markdown file off those comments. #>
$ModulePath = '.\Oz.psm1'
$OutputFile = '.\README.md'

Import the module, capture the module name, and begin formatting our output string:

Import-Module $modulepath -Force

$modulename = (Split-Path -Path $ModulePath -Leaf).Split('.')[0]

$output = @()
$output += "# $modulename"
$output += ''

Here, I let Get-Command and Get-Help do the heavy lifting. Calling Get-Help on a cmdlet will return the standard comments within that cmdlet’s definition. Comments like .NOTES, .SYNOPSIS, or .DESCRIPTION. Loop through the commands within the module and process the help results:

foreach($cmdlet in (Get-Command -Module $modulename)) {
$helpresults = Get-Help $cmdlet

$name = $helpresults.Name
$synop = $helpresults.Synopsis
$notes = $helpresults.alertSet.alert[0].Text.Split("`n")

#Add the results to the output array
$output += "## $name"
$output += ''

#I use multiple lines in .NOTES, so process each line.
foreach ($line in $notes) {
#The added ' ' is used to start a new line in markdown.
$output += ($line + ' ')
}

$output += ''
$output += "$synop"
$output += ''
}

Finally, write the output array to your markdown file.

$output | Out-File -FilePath $OutputFile -Force -Encoding ascii

And here's the payoff:

# Oz

## New-Witch

NAME: New-Witch
AUTHOR: James Livingston
CREATED: 1939

Creates a new wicked witch.

## Remove-Witch

NAME: Remove-Witch
AUTHOR: James Livingston
CREATED: 1939

Function to kill the wicked witch.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.