Autodocument your Powershell modules using Markdown

AutoMarkdown.ps1

param
(
    [string]$PathToModule='C:\temp\Cos.psm1',
    [string]$ModuleName = 'cos',
    [string]$OutputFolderPath='C:\temp',
    [string]$ResultFileNamePrefix='cos_module',
    [string]$ResultFileNameSuffix = 'md'
)



function Generate-TemporaryFile
{
    <#
        .SYNOPSIS
        Function used to generate a temporary file

        .DESCRIPTION
        Generates new files in temporary folder. The method of creation depends on Powershell version used

    #>
    
    if($PSVersionTable.PSVersion.Major -ge 5)
    {
        return New-TemporaryFile
    }
    else
    {
        return (new-item -ItemType File -Path $env:TEMP -Name (New-Guid).Guid)
    }

}






    $arrParameterProperties = @(
        'DefaultValue',
        'ParameterValue',
        'PipelineInput',
        'Position',
        'Required'
    )

    # Prepare output file name which is temporary due to UTF conversion
    $outputFile = (Generate-TemporaryFile).FullName


    # Create header and output it to the file - replace destination if exists (by using force param )
    "# PowerShell module `r`n" | Out-File -FilePath $outputFile  -Force
    
    # import module which we will be working with (using force to be sure we have newest loaded )
    $Module = import-module $PathToModule -Force


    # iterate through functions
    foreach ($singleFunction in (Get-Command -Module $ModuleName).Name )
    {
        
        # Get functionHelp for current function 
        $functionfunctionHelp = Get-Help $singleFunction -ErrorAction 'SilentlyContinue'
        
        # Add function base name  
        '## [' + $singleFunction + ']'| Out-File -FilePath $outputFile -Append 

        # Add Synopsis
        if ($functionfunctionHelp.Synopsis)
        {
            '## Synopsis' | Out-File -FilePath $outputFile -Append 
            $functionHelp.Synopsis + " `r`n" | Out-File -FilePath $outputFile -Append 
        } 

        # Add Syntax
        if ($functionHelp.Syntax)
        {
            '## Syntax' | Out-File -FilePath $outputFile -Append 
            "``````PowerShell`r`n" + ($functionHelp.Syntax | Out-String).trim() + "`r`n``````" | Out-File -FilePath $outputFile -Append 
        } 
          
        # Add Description         
        if ($functionHelp.Description)
        {
            '## Description' | Out-File -FilePath $outputFile -Append 
            $functionHelp.Description.Text + "`r`n" | Out-File -FilePath $outputFile -Append 
        } 

        # Add parameters
        if ($functionHelp.Parameters)
            {
                '## Parameters' | Out-File -FilePath $outputFile -Append 
                forEach ($item in $functionHelp.Parameters.Parameter)
                {
                    '### ' + $item.name | Out-File -FilePath $outputFile -Append 
                    $item.Description + "`r`n" | Out-File -FilePath $outputFile -Append 
                    '- **Type**: ' + $item.Type.Name | Out-File -FilePath $outputFile -Append 
                    forEach ($arrParameterProperty in $arrParameterProperties)
                    {
                        if ($item.$arrParameterProperty)
                        {
                            "- **$arrParameterProperty**: " + $item.$arrParameterProperty | Out-File -FilePath $outputFile -Append  
                        }

                    }
                }
        } 

        # Add examples
        if ($functionHelp.Examples)
        {
            "## Examples `r`n" | Out-File -FilePath $outputFile -Append 
            forEach ($item in $functionHelp.Examples.Example)
            {
                "`r`n### " + $item.title.Replace('-','').Replace('EXAMPLE','Example') | Out-File -FilePath $outputFile -Append                     
                if ($item.Code)
                {
                    "``````PowerShell`r`n" + $item.Code + "`r`n``````" | Out-File -FilePath $outputFile -Append 
                }
                if ($item.Remarks)
                {
                    $item.Remarks | Out-File -FilePath $outputFile -Append 
                }
            }
        } 






}


    # Convert to UTF-8 afterwards 
    $finalFileName = [string]::Format('{0}\{1}.{2}',$OutputFolderPath,$ResultFileNamePrefix,$ResultFileNameSuffix)
    [System.Io.File]::ReadAllText($outputFile) | Out-File -FilePath $finalFileName -Encoding utf8

    #remove temporary file
    Remove-Item $outputFile -Force