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