DSCResource.Tests/DscResource.DocumentationHelper/PowerShellHelp.psm1

<#
.SYNOPSIS
 
New-DscResourcePowerShellHelp generates PowerShell compatable help files for a DSC
resource module
 
.DESCRIPTION
 
The New-DscResourcePowerShellHelp cmdlet will review all of the MOF based resources
in a specified module directory and will inject PowerShell help files for each resource
in to the specified directory. These help files include details on the property types for
each resource, as well as a text description and examples where they exist.
 
.PARAMETER OutputPath
 
Where should the files be saved to (ususally the "en-US" folder inside the module for US english)
 
.PARAMETER ModulePath
 
The path to the root of the DSC resource module (where the PSD1 file is found, not the folder for
and individual DSC resource)
 
.EXAMPLE
 
This example shows how to generate help for a specific module
 
    New-DscResourcePowerShellHelp -ModulePath C:\repos\SharePointdsc -OutputPath C:\repos\SharePointDsc\en-US
 
#>

function New-DscResourcePowerShellHelp
{
    [CmdletBinding()]
    param
    (
        [parameter(Mandatory = $true)]
        [System.String]
        $OutputPath,

        [parameter(Mandatory = $true)]
        [System.String]
        $ModulePath
    )

    Import-Module (Join-Path -Path $PSScriptRoot -ChildPath "MofHelper.psm1")

    $mofSearchPath = (Join-Path -Path $ModulePath -ChildPath "\**\*.schema.mof")
    $mofSchemas = Get-ChildItem -Path $mofSearchPath -Recurse
    $mofSchemas | ForEach-Object {
        $mofFileObject = $_

        $descriptionPath = Join-Path -Path $_.DirectoryName -ChildPath "readme.md"
        if (Test-Path -Path $descriptionPath)
        {
            $result = (Get-MofSchemaObject -FileName $_.FullName) | Where-Object {
                ($_.ClassName -eq $mofFileObject.Name.Replace(".schema.mof", "")) `
                    -and ($null -ne $_.FriendlyName)
            }
            Write-Verbose -Message "Generating help document for $($result.FriendlyName)"

            $output = ".NAME" + [Environment]::NewLine
            $output += " $($result.FriendlyName)"
            $output += [Environment]::NewLine + [Environment]::NewLine

            $descriptionContent = Get-Content -Path $descriptionPath -Raw
            $descriptionContent = $descriptionContent.Replace("**Description**", ".DESCRIPTION")
            $descriptionContent = $descriptionContent -replace "\n", "`n "

            $output += $descriptionContent
            $output += [Environment]::NewLine

            foreach ($property in $result.Attributes)
            {
                $output += ".PARAMETER $($property.Name)" + [Environment]::NewLine
                $output += " $($property.State) - $($property.DataType)"
                $output += [Environment]::NewLine

                if ([string]::IsNullOrEmpty($property.ValueMap) -ne $true)
                {
                    $output += " Allowed values: "
                    $property.ValueMap | ForEach-Object {
                        $output += $_ + ", "
                    }
                    $output = $output.TrimEnd(" ")
                    $output = $output.TrimEnd(",")
                    $output +=  [Environment]::NewLine
                }
                $output += " " + $property.Description
                $output += [Environment]::NewLine + [Environment]::NewLine
            }

            $exampleSearchPath = "\Examples\Resources\$($result.FriendlyName)\*.ps1"
            $examplesPath = (Join-Path -Path $ModulePath -ChildPath $exampleSearchPath)
            $exampleFiles = Get-ChildItem -Path $examplesPath -ErrorAction SilentlyContinue

            if ($null -ne $exampleFiles)
            {
                foreach ($exampleFile in $exampleFiles)
                {
                    $exampleContent = Get-Content -Path $exampleFile.FullName -Raw
                    $exampleContent = $exampleContent -replace "<#"
                    $exampleContent = $exampleContent -replace "#>"

                    $output += $exampleContent
                    $output += [Environment]::NewLine
                }
            }

            $savePath = Join-Path -Path $OutputPath -ChildPath "about_$($result.FriendlyName).help.txt"
            $output | Out-File -FilePath $savePath -Encoding utf8 -Force
        }
    }
}

Export-ModuleMember -Function *