DscResource.DocGenerator

0.9.0-preview0006

DscResource.DocGenerator.psm1

#Region './prefix.ps1' 0
# This is added to the top of the generated file module file.

$script:resourceHelperModulePath = Join-Path -Path $PSScriptRoot -ChildPath '.\Modules\DscResource.Common'

Import-Module -Name $script:resourceHelperModulePath

$script:localizedData = Get-LocalizedData -DefaultUICulture 'en-US'

<#
    Define enumeration for use by help example generation to determine the type of
    block that a text line is within.
#>
if (-not ([System.Management.Automation.PSTypeName]'HelpExampleBlockType').Type)
{
    $typeDefinition = @'
    public enum HelpExampleBlockType
    {
        None,
        PSScriptInfo,
        Configuration,
        ExampleCommentHeader
    }
'@
    Add-Type -TypeDefinition $typeDefinition
}

<#
    Define enumeration for use by wiki example generation to determine the type of
    block that a text line is within.
#>
if (-not ([System.Management.Automation.PSTypeName]'WikiExampleBlockType').Type)
{
    $typeDefinition = @'
    public enum WikiExampleBlockType
    {
        None,
        PSScriptInfo,
        Configuration,
        ExampleCommentHeader
    }
'@
    Add-Type -TypeDefinition $typeDefinition
}
#EndRegion './prefix.ps1' 44
#Region './Private/Copy-WikiFolder.ps1' 0
<#
    .SYNOPSIS
        Copies any Wiki files from the module into the Wiki and optionally overwrite
        any existing files.

    .DESCRIPTION
        Copies any Wiki files from the module into the Wiki and optionally overwrite
        any existing files.

    .PARAMETER Path
        The path to the output that was generated by New-DscResourceWikiPage.

    .PARAMETER DestinationPath
        The destination path for the Wiki files.

    .PARAMETER WikiSourcePath
        The name of the folder that contains the source Wiki files.

    .PARAMETER Force
        If present, copies files forcefully, overwriting any existing files.

    .EXAMPLE
        Copy-WikiFolder -Path '.\output\WikiContent' -DestinationPath 'c:\repoName.wiki.git' -WikiSourcePath '.\source\WikiSource'

        Copies any Wiki files from the module into the Wiki.
#>
function Copy-WikiFolder
{
    [CmdletBinding()]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.String]
        $Path,

        [Parameter(Mandatory = $true)]
        [System.String]
        $DestinationPath,

        [Parameter()]
        [System.Management.Automation.SwitchParameter]
        $Force
    )

    Write-Verbose -Message ($localizedData.CopyWikiFoldersMessage -f ($Path -join ''', '''))

    $wikiFiles = Get-ChildItem -Path $Path

    foreach ($file in $wikiFiles)
    {
        Write-Verbose -Message ($localizedData.CopyFileMessage -f $file.Name)

        Copy-Item -Path $file.FullName -Destination $DestinationPath -Force:$Force
    }
}
#EndRegion './Private/Copy-WikiFolder.ps1' 56
#Region './Private/Format-Text.ps1' 0
<#
    .SYNOPSIS
        Formats a string using predefined format options.

    .DESCRIPTION
        Formats a string using predefined format options.

    .PARAMETER Text
        Specifies the string to format.

    .PARAMETER Format
        One or more predefined format options. The formatting is done in the
        provided order.

    .EXAMPLE
        Format-Text -Text 'My text description' -Format @('Replace_Multiple_Whitespace_With_One')

        Returns a string correctly formatted with one whitespace between each word.
#>
function Format-Text
{
    [CmdletBinding()]
    [OutputType([System.String])]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.String]
        $Text,

        [Parameter(Mandatory = $true)]
        [ValidateSet(
            'Replace_Multiple_Whitespace_With_One',
            'Remove_Blank_Rows_At_End_Of_String',
            'Remove_Indentation_From_Blank_Rows',
            'Replace_NewLine_With_One_Whitespace',
            'Replace_Vertical_Bar_With_One_Whitespace',
            'Remove_Whitespace_From_End_Of_String'
        )]
        [System.String[]]
        $Format
    )

    $returnString = $Text

    switch ($Format)
    {
        # Replace multiple whitespace with one single white space
        'Replace_Multiple_Whitespace_With_One'
        {
            $returnString = $returnString -replace ' +', ' '
        }

        # Removes all blank rows at the end
        'Remove_Blank_Rows_At_End_Of_String'
        {
            $returnString = $returnString -replace '[\r?\n]+$'
        }

        # Remove all indentations from blank rows
        'Remove_Indentation_From_Blank_Rows'
        {
            $returnString = $returnString -replace '[ ]+\r\n', "`r`n"
            $returnString = $returnString -replace '[ ]+\n', "`n"
        }

        # Replace LF or CRLF with one white space
        'Replace_NewLine_With_One_Whitespace'
        {
            $returnString = $returnString -replace '\r?\n', ' '
        }

        # Replace vertical bar with one white space
        'Replace_Vertical_Bar_With_One_Whitespace'
        {
            $returnString = $returnString -replace '\|', ' '
        }

        # Remove white space from end of string
        'Remove_Whitespace_From_End_Of_String'
        {
            $returnString = $returnString -replace ' +$'
        }
    }

    return $returnString
}
#EndRegion './Private/Format-Text.ps1' 87
#Region './Private/Get-ClassAst.ps1' 0
<#
    .SYNOPSIS
        Returns the AST for a single or all classes.

    .DESCRIPTION
        Returns the AST for a single or all classes.

    .PARAMETER ScriptFile
        The path to the source file that contain the class.

    .PARAMETER ClassName
        The specific class to return the AST for. Optional.

    .EXAMPLE
        Get-ClassAst -ScriptFile '.\output\MyModule\1.0.0\MyModule.psm1'

        Returns AST for all the classes in the script file.

    .EXAMPLE
        Get-ClassAst -ClassName 'myClass' -ScriptFile '.\output\MyModule\1.0.0\MyModule.psm1'

        Returns AST for the class 'myClass' from the script file.
#>
function Get-ClassAst
{
    [CmdletBinding()]
    [OutputType([System.Collections.Generic.IEnumerable`1[System.Management.Automation.Language.Ast]])]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.String]
        $ScriptFile,

        [Parameter()]
        [System.String]
        $ClassName
    )

    $tokens, $parseErrors = $null

    $ast = [System.Management.Automation.Language.Parser]::ParseFile($ScriptFile, [ref] $tokens, [ref] $parseErrors)

    if ($parseErrors)
    {
        throw $parseErrors
    }

    if ($PSBoundParameters.ContainsKey('ClassName') -and $ClassName)
    {
        # Get only the specific class resource.
        $astFilter = {
            $args[0] -is [System.Management.Automation.Language.TypeDefinitionAst] `
                -and $args[0].IsClass `
                -and $args[0].Name -eq $ClassName
        }
    }
    else
    {
        # Get all class resources.
        $astFilter = {
            $args[0] -is [System.Management.Automation.Language.TypeDefinitionAst] `
                -and $args[0].IsClass
        }
    }

    $classAst = $ast.FindAll($astFilter, $true)

    return $classAst
}
#EndRegion './Private/Get-ClassAst.ps1' 70
#Region './Private/Get-ClassResourceAst.ps1' 0
<#
    .SYNOPSIS
        Returns the AST for a single or all DSC class resources.

    .DESCRIPTION
        Returns the AST for a single or all DSC class resources.

    .PARAMETER ScriptFile
        The path to the source file that contain the DSC class resource.

    .PARAMETER ClassName
        The specific DSC class resource to return the AST for. Optional.

    .EXAMPLE
        Get-ClassResourceAst -ClassName 'myClass' -ScriptFile '.\output\MyModule\1.0.0\MyModule.psm1'

        Returns AST for all DSC class resources in the script file.

    .EXAMPLE
        Get-ClassResourceAst -ClassName 'myClass' -ScriptFile '.\output\MyModule\1.0.0\MyModule.psm1'

        Returns AST for the DSC class resource 'myClass' from the script file.
#>
function Get-ClassResourceAst
{
    [CmdletBinding()]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.String]
        $ScriptFile,

        [Parameter()]
        [System.String]
        $ClassName
    )

    $dscClassResourceAst = $null

    $getClassAstParameters = @{
        ScriptFile = $ScriptFile
    }

    if ($PSBoundParameters.ContainsKey('ClassName'))
    {
        $getClassAstParameters['ClassName'] = $ClassName
    }

    $ast = Get-ClassAst @getClassAstParameters

    # Only try to filter if there was at least one class returned.
    if ($ast)
    {
        # Get only DSC class resource.
        $astFilter = {
            $args[0] -is [System.Management.Automation.Language.TypeDefinitionAst] `
                -and $args[0].IsClass `
                -and $args[0].Attributes.Extent.Text -imatch '\[DscResource\(.*\)\]'
        }

        $dscClassResourceAst = $ast.FindAll($astFilter, $true)
    }

    return $dscClassResourceAst
}
#EndRegion './Private/Get-ClassResourceAst.ps1' 66
#Region './Private/Get-ClassResourceProperty.ps1' 0
<#
    .SYNOPSIS
        Returns DSC class resource properties from the provided class or classes.

    .DESCRIPTION
        Returns DSC class resource properties from the provided class or classes.

    .PARAMETER SourcePath
        The path to the source folder (in which the child folder 'Classes' exist).

    .PARAMETER BuiltModuleScriptFilePath
        The path to the built module script file that contains the class.

    .PARAMETER ClassName
        One or more class names to return properties for.

    .EXAMPLE
        Get-ClassResourceProperty -ClassName @('myParentClass', 'myClass') -BuiltModuleScriptFilePath '.\output\MyModule\1.0.0\MyModule.psm1' -SourcePath '.\source'

        Returns all DSC class resource properties.
#>
function Get-ClassResourceProperty
{
    [CmdletBinding()]
    [OutputType([System.Collections.Hashtable[]])]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.String]
        $SourcePath,

        [Parameter(Mandatory = $true)]
        [System.String]
        $BuiltModuleScriptFilePath,

        [Parameter(Mandatory = $true)]
        [System.String[]]
        $ClassName
    )

    $resourceProperty = [System.Collections.Hashtable[]] @()

    foreach ($currentClassName in $ClassName)
    {
        $dscResourceAst = Get-ClassAst -ClassName $currentClassName -ScriptFile $BuiltModuleScriptFilePath

        $sourceFilePath = Join-Path -Path $SourcePath -ChildPath ('Classes/*{0}.ps1' -f $currentClassName)

        $dscResourceCommentBasedHelp = Get-CommentBasedHelp -Path $sourceFilePath

        $astFilter = {
            $args[0] -is [System.Management.Automation.Language.PropertyMemberAst] `
                -and $args[0].Attributes.TypeName.Name -eq 'DscProperty'
        }

        $propertyMemberAsts = $dscResourceAst.FindAll($astFilter, $true)

        <#
            Looping through each resource property to build the resulting
            hashtable. Hashtable will be in the format:

            @{
                Name = <System.String>
                State = 'Key' | 'Required' |'Write' | 'Read'
                Description = <System.String>
                EmbeddedInstance = 'MSFT_Credential' | $null
                DataType = 'System.String' | 'System.String[] | etc.
                IsArray = $true | $false
                ValueMap = @(<System.String> | ...)
            }
        #>
        foreach ($propertyMemberAst in $propertyMemberAsts)
        {
            Write-Verbose -Message ($script:localizedData.FoundClassResourcePropertyMessage -f $propertyMemberAst.Name, $dscResourceAst.Name)

            $propertyAttribute = @{
                Name             = $propertyMemberAst.Name
                DataType         = $propertyMemberAst.PropertyType.TypeName.FullName

                # Always set to null, correct type name is set in DataType.
                EmbeddedInstance = $null

                # Always set to $false - correct type name is set in DataType.
                IsArray          = $false
            }

            $propertyAttribute['State'] = Get-ClassResourcePropertyState -Ast $propertyMemberAst

            $astFilter = {
                $args[0] -is [System.Management.Automation.Language.AttributeAst] `
                    -and $args[0].TypeName.Name -eq 'ValidateSet'
            }

            $propertyAttributeAsts = $propertyMemberAst.FindAll($astFilter, $true)

            if ($propertyAttributeAsts)
            {
                $propertyAttribute['ValueMap'] = $propertyAttributeAsts.PositionalArguments.Value
            }

            if ($dscResourceCommentBasedHelp -and $dscResourceCommentBasedHelp.Parameters.Count -gt 0)
            {
                # The key name must be upper-case for it to match the right item in the list of parameters.
                $propertyDescription = $dscResourceCommentBasedHelp.Parameters[$propertyMemberAst.Name.ToUpper()]

                if ($propertyDescription)
                {
                    $propertyDescription = Format-Text -Text $propertyDescription -Format @(
                        'Remove_Blank_Rows_At_End_Of_String',
                        'Remove_Indentation_From_Blank_Rows',
                        'Replace_NewLine_With_One_Whitespace',
                        'Replace_Vertical_Bar_With_One_Whitespace',
                        'Replace_Multiple_Whitespace_With_One',
                        'Remove_Whitespace_From_End_Of_String'
                    )
                }
            }
            else
            {
                $propertyDescription = ''
            }

            $propertyAttribute['Description'] = $propertyDescription

            $resourceProperty += $propertyAttribute
        }
    }

    return $resourceProperty
}
#EndRegion './Private/Get-ClassResourceProperty.ps1' 131
#Region './Private/Get-ClassResourcePropertyState.ps1' 0
<#
    .SYNOPSIS
        This function returns the property state value of an class-based DSC
        resource property.

    .DESCRIPTION
        This function returns the property state value of an DSC class-based
        resource property.

    .PARAMETER Ast
        The Abstract Syntax Tree (AST) for class-based DSC resource property.
        The passed value must be an AST of the type 'PropertyMemberAst'.

    .EXAMPLE
        Get-ClassResourcePropertyState -Ast {
            [DscResource()]
            class NameOfResource {
                [DscProperty(Key)]
                [string] $KeyName

                [NameOfResource] Get() {
                    return $this
                }

                [void] Set() {}

                [bool] Test() {
                    return $true
                }
            }
        }.Ast.Find({$args[0] -is [System.Management.Automation.Language.PropertyMemberAst]}, $false)

        Returns the property state for the property 'KeyName'.
#>
function Get-ClassResourcePropertyState
{
    [CmdletBinding()]
    [OutputType([System.String])]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.Management.Automation.Language.PropertyMemberAst]
        $Ast
    )

    <#
        Check for Key first since it it possible to use both Key and Mandatory
        on a property and in that case we want to return just 'Key'.
    #>
    if ((Test-PropertyMemberAst -IsKey -Ast $Ast))
    {
        $propertyState = 'Key'
    }
    elseif ((Test-PropertyMemberAst -IsMandatory -Ast $Ast))
    {
        $propertyState = 'Required'
    }
    elseif ((Test-PropertyMemberAst -IsRead -Ast $Ast))
    {
        $propertyState = 'Read'
    }
    elseif ((Test-PropertyMemberAst -IsWrite -Ast $Ast))
    {
        $propertyState = 'Write'
    }

    return $propertyState
}
#EndRegion './Private/Get-ClassResourcePropertyState.ps1' 69
#Region './Private/Get-CommentBasedHelp.ps1' 0
<#
    .SYNOPSIS
        Get-CommentBasedHelp returns comment-based help from a PowerShell
        script file.

    .DESCRIPTION
        Get-CommentBasedHelp returns comment-based help for a PowerShell script
        file by parsing the source PowerShell script file. If the comment block
        is not the first element in the file then the first comment block will
        be located and everything before it will be removed before parsing.

    .PARAMETER Path
        The path to the PowerShell script file. This should be a
        PowerShell script file that contains one resource with the
        comment-based help at the top of the file.

    .OUTPUTS
        System.Management.Automation.Language.CommentHelpInfo

    .EXAMPLE
        $commentBasedHelp = Get-CommentBasedHelp -Path 'c:\MyProject\source\Classes\010-MyResourceName.ps1'

        This example parses the comment-based help from the PowerShell script file
        'c:\MyProject\source\Classes\010-MyResourceName.ps1' and returns an
        object of System.Management.Automation.Language.CommentHelpInfo.

    .NOTES
        PowerShell classes do not support comment-based help. There is
        no GetHelpContent() on the TypeDefinitionAst.

        We use the ScriptBlockAst to filter out our class-based resource
        script block from the source file and use that to get the
        comment-based help.
#>
function Get-CommentBasedHelp
{
    [CmdletBinding()]
    [OutputType([System.Management.Automation.Language.CommentHelpInfo])]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.String]
        $Path
    )

    $Path = Resolve-Path -Path $Path

    Write-Verbose -Message ($script:localizedData.CommentBasedHelpMessage -f $Path)

    $scriptContent = Get-Content -Path $Path -Raw

    # Ensure the comment-based help block is at the top of the file.
    $regexOptions = [System.Text.RegularExpressions.RegexOptions]::Multiline
    $firstCommentBlockStart = [System.Text.RegularExpressions.Regex]::Match($scriptContent, "^<#(\n|\r|\r\n)$", $regexOptions)

    if ($firstCommentBlockStart.Success)
    {
        Write-Verbose -Message ($script:localizedData.CommentBasedHelpBlockNotAtTopMessage -f $Path)
        $scriptContent = $scriptContent.Substring($firstCommentBlockStart.Index)
    }
    else
    {
        Write-Warning -Message (
            $script:localizedData.CommentBasedHelpBlockNotFound -f $Path
        )
    }

    $tokens, $parseErrors = $null

    $ast = [System.Management.Automation.Language.Parser]::ParseInput($scriptContent, [ref] $tokens, [ref] $parseErrors)

    if ($parseErrors)
    {
        <#
            Normally we should throw if there is any parse errors but in the case
            of the class-based resource source file that is not possible. If the
            class is inheriting from a base class that base class is not part of
            the source script file which will generate a parse error.
            Even with parse errors the comment-based help is available with
            GetHelpContent(). The errors are outputted for debug purposes, if there
            would be a future problem that we have not taken account for.
        #>
        Write-Debug -Message (
            $script:localizedData.IgnoreAstParseErrorMessage -f ($parseErrors | Out-String)
        )
    }

    $dscResourceCommentBasedHelp = $ast.GetHelpContent()

    return $dscResourceCommentBasedHelp
}
#EndRegion './Private/Get-CommentBasedHelp.ps1' 92
#Region './Private/Get-CompositeResourceParameterState.ps1' 0
<#
    .SYNOPSIS
        This function returns the parameter state of a composite
        resource parameter.

    .DESCRIPTION
        This function returns the parameter state of a composite
        resource parameter. It will return 'Required' if the parameter
        has the 'Mandatory = $true' attribute set.

    .PARAMETER Ast
        The Abstract Syntax Tree (AST) for composite composite resource
        parameter. The passed value must be an AST of the type 'ParameterAst'.

    .EXAMPLE
        Get-CompositeResourceParameterState -Ast {
            configuration CompositeHelperTest
            {
                [CmdletBinding()]
                param
                (
                    [Parameter(Mandatory = $true)]
                    [ValidateNotNullOrEmpty()]
                    [System.String[]]
                    $Name
                )
            }
        }.Ast.Find({$args[0] -is [System.Management.Automation.Language.ParameterAst]}, $false)

        Returns the parameter state for the parameter 'Name' which will be 'Required'.

    .NOTES
        MacOS is not currently supported because DSC can not be installed on it.
        DSC is required to process the AST for the configuration statement.

#>
function Get-CompositeResourceParameterState
{
    [CmdletBinding()]
    [OutputType([System.String])]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.Management.Automation.Language.ParameterAst]
        $Ast
    )

    if ($IsMacOS)
    {
        throw $script:localizedData.MacOSNotSupportedError
    }

    $astFilterForMandatoryAttribute = {
        $args[0] -is [System.Management.Automation.Language.AttributeAst] `
            -and $args[0].TypeName.Name -eq 'Parameter' `
            -and $args[0].NamedArguments.ArgumentName -eq 'Mandatory' `
            -and $args[0].NamedArguments.Argument.Extent.Text -eq '$true'
    }

    if ($Ast.FindAll($astFilterForMandatoryAttribute, $false))
    {
        $parameterState = 'Required'
    }
    else
    {
        $parameterState = 'Write'
    }

    return $parameterState
}
#EndRegion './Private/Get-CompositeResourceParameterState.ps1' 71
#Region './Private/Get-CompositeResourceParameterValidateSet.ps1' 0
<#
    .SYNOPSIS
        This function returns the parameter validate set of a composite
        resource parameter.

    .DESCRIPTION
        This function returns the parameter validate set of a composite
        resource parameter. It will return an array of value found in
        the 'ValidateSet' attribute for the parameter.

    .PARAMETER Ast
        The Abstract Syntax Tree (AST) for composite composite resource
        parameter. The passed value must be an AST of the type 'ParameterAst'.

    .EXAMPLE
        Get-CompositeResourceParameterValidateSet -Ast {
            configuration CompositeHelperTest
            {
                [CmdletBinding()]
                param
                (
                    [Parameter()]
                    [ValidateSet('Present', 'Absent')]
                    [System.String]
                    $Ensure
                )
            }
        }.Ast.Find({$args[0] -is [System.Management.Automation.Language.ParameterAst]}, $false)

        Returns the parameter validate set for the parameter 'Enure' which will be 'Present', 'Absent'.

    .NOTES
        MacOS is not currently supported because DSC can not be installed on it.
        DSC is required to process the AST for the configuration statement.
#>
function Get-CompositeResourceParameterValidateSet
{
    [CmdletBinding()]
    [OutputType([System.String[]])]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.Management.Automation.Language.ParameterAst]
        $Ast
    )

    if ($IsMacOS)
    {
        throw $script:localizedData.MacOSNotSupportedError
    }

    $astFilterForValidateSetAttribute = {
        $args[0] -is [System.Management.Automation.Language.AttributeAst] `
            -and $args[0].TypeName.Name -eq 'ValidateSet'
    }

    $validateSetAttribute = $Ast.FindAll($astFilterForValidateSetAttribute, $false)

    if ($validateSetAttribute)
    {
        return $validateSetAttribute.PositionalArguments.Value
    }
}
#EndRegion './Private/Get-CompositeResourceParameterValidateSet.ps1' 64
#Region './Private/Get-CompositeSchemaObject.ps1' 0
<#
    .SYNOPSIS
        Get-CompositeSchemaObject is used to read a .schema.psm1 file for a
        composite DSC resource.

    .DESCRIPTION
        The Get-CompositeSchemaObject method is used to read the text content of the
        .schema.psm1 file that all composite DSC resources have. It also reads the .psd1
        file to pull the module version. The object that is returned contains all of the
        data in the schema and manifest so it can be processed in other scripts.

    .PARAMETER FileName
        The full path to the .schema.psm1 file to process.

    .EXAMPLE
        $mof = Get-CompositeSchemaObject -FileName C:\repos\xPSDesiredStateConfiguration\DSCRescoures\xGroupSet\xGroupSet.schema.psm1

        This example parses a composite schema file and composite manifest file.

    .NOTES
        MacOS is not currently supported because DSC can not be installed on it.
        DSC is required to process the AST for the configuration statement.
#>
function Get-CompositeSchemaObject
{
    [CmdletBinding()]
    [OutputType([System.Collections.Hashtable])]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.String]
        $FileName
    )

    if ($IsMacOS)
    {
        throw $script:localizedData.MacOSNotSupportedError
    }

    $manifestFileName = $FileName -replace '.schema.psm1','.psd1'
    $compositeName = [System.IO.Path]::GetFileName($FileName) -replace '.schema.psm1',''
    $manifestData = Import-LocalizedData `
        -BaseDirectory ([System.IO.Path]::GetDirectoryName($manifestFileName)) `
        -FileName ([System.IO.Path]::GetFileName($manifestFileName))
    $moduleVersion = $manifestData.ModuleVersion
    $description = $manifestData.Description
    $compositeResource = Get-ConfigurationAst -ScriptFile $FileName

    if ($compositeResource.Count -gt 1)
    {
        throw ($script:localizedData.CompositeResourceMultiConfigError -f $FileName, $compositeResources.Count)
    }

    $commentBasedHelp = Get-CommentBasedHelp -Path $FileName

    $parameters = foreach ($parameter in $compositeResource.Body.ScriptBlock.ParamBlock.Parameters)
    {
        $parameterName = $parameter.Name.VariablePath.ToString()

        # The parameter name in comment-based help is returned as upper so need to match correctly.
        $parameterDescription = $commentBasedHelp.Parameters[$parameterName.ToUpper()] -replace '\r?\n+$'

        @{
            Name             = $parameterName
            State            = (Get-CompositeResourceParameterState -Ast $parameter)
            Type             = $parameter.StaticType.FullName
            ValidateSet      = (Get-CompositeResourceParameterValidateSet -Ast $parameter)
            Description      = $parameterDescription
        }
    }

    return @{
        Name          = $compositeName
        Parameters    = $parameters
        ModuleVersion = $moduleVersion
        Description   = $description
    }
}
#EndRegion './Private/Get-CompositeSchemaObject.ps1' 79
#Region './Private/Get-ConfigurationAst.ps1' 0
<#
    .SYNOPSIS
        Returns the AST for a single or all configurations.

    .DESCRIPTION
        Returns the AST for a single or all configurations.

    .PARAMETER ScriptFile
        The path to the source file that contain the configuration.

    .PARAMETER ConfigurationName
        The specific configuration to return the AST for. Optional.

    .EXAMPLE
        Get-ConfigurationAst -ScriptFile '.\output\myModule\1.0.0\DSCResources\myComposite\myComposite.schema.psm1'

        Returns AST for all the DSC configurations in the script file.

    .EXAMPLE
        Get-ConfigurationAst -ConfigurationName 'myComposite' -ScriptFile '.\output\myModule\1.0.0\DSCResources\myComposite\myComposite.schema.psm1'

        Returns AST for the DSC configuration 'myComposite' from the script file.

    .NOTES
        MacOS is not currently supported because DSC can not be installed on it.
        DSC is required to process the AST for the configuration statement.
#>
function Get-ConfigurationAst
{
    [CmdletBinding()]
    [OutputType([System.Collections.Generic.IEnumerable`1[System.Management.Automation.Language.Ast]])]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.String]
        $ScriptFile,

        [Parameter()]
        [System.String]
        $ConfigurationName
    )

    if ($IsMacOS)
    {
        throw $script:localizedData.MacOSNotSupportedError
    }

    $tokens, $parseErrors = $null

    $ast = [System.Management.Automation.Language.Parser]::ParseFile($ScriptFile, [ref] $tokens, [ref] $parseErrors)

    if ($parseErrors)
    {
        throw $parseErrors
    }

    if ($PSBoundParameters.ContainsKey('ConfigurationName') -and $ConfigurationName)
    {
        # Get only the specific composite resources.
        $astFilter = {
            $args[0] -is [System.Management.Automation.Language.ConfigurationDefinitionAst] `
                -and $args[0].ConfigurationType -eq [System.Management.Automation.Language.ConfigurationType]::Resource `
                -and $args[0].InstanceName.Value -eq $ConfigurationName
        }
    }
    else
    {
        # Get all composite resources.
        $astFilter = {
            $args[0] -is [System.Management.Automation.Language.ConfigurationDefinitionAst] `
            -and $args[0].ConfigurationType -eq [System.Management.Automation.Language.ConfigurationType]::Resource `
        }
    }

    $configurationAst = $ast.FindAll($astFilter, $true)

    return $configurationAst
}
#EndRegion './Private/Get-ConfigurationAst.ps1' 79
#Region './Private/Get-DscResourceHelpExampleContent.ps1' 0
<#
    .SYNOPSIS
        This function reads an example file from a resource and converts
        it to help text for inclusion in a PowerShell help file.

    .DESCRIPTION
        The function will read the example PS1 file and convert the
        help header into the description text for the example.

    .PARAMETER ExamplePath
        The path to the example file.

    .PARAMETER ExampleNumber
        The (order) number of the example.

    .EXAMPLE
        Get-DscResourceHelpExampleContent -ExamplePath 'C:\repos\NetworkingDsc\Examples\Resources\DhcpClient\1-DhcpClient_EnableDHCP.ps1' -ExampleNumber 1

        Reads the content of 'C:\repos\NetworkingDsc\Examples\Resources\DhcpClient\1-DhcpClient_EnableDHCP.ps1'
        and converts it to help text in preparation for being added to a PowerShell help file.
#>
function Get-DscResourceHelpExampleContent
{
    [CmdletBinding()]
    [OutputType([System.String])]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.String]
        $ExamplePath,

        [Parameter(Mandatory = $true)]
        [System.Int32]
        $ExampleNumber
    )

    $exampleContent = Get-Content -Path $ExamplePath

    # Use a string builder to assemble the example description and code
    $exampleDescriptionStringBuilder = New-Object -TypeName System.Text.StringBuilder
    $exampleCodeStringBuilder = New-Object -TypeName System.Text.StringBuilder

    <#
        Step through each line in the source example and determine
        the content and act accordingly:
        \<#PSScriptInfo...#\> - Drop block
        \#Requires - Drop Line
        \<#...#\> - Drop .EXAMPLE, .SYNOPSIS and .DESCRIPTION but include all other lines
        Configuration ... - Include entire block until EOF
    #>
    $blockType = [HelpExampleBlockType]::None

    foreach ($exampleLine in $exampleContent)
    {
        Write-Debug -Message ('Processing Line: {0}' -f $exampleLine)

        # Determine the behavior based on the current block type
        switch ($blockType.ToString())
        {
            'PSScriptInfo'
            {
                Write-Debug -Message 'PSScriptInfo Block Processing'

                # Exclude PSScriptInfo block from any output
                if ($exampleLine -eq '#>')
                {
                    Write-Debug -Message 'PSScriptInfo Block Ended'

                    # End of the PSScriptInfo block
                    $blockType = [HelpExampleBlockType]::None
                }
            }

            'Configuration'
            {
                Write-Debug -Message 'Configuration Block Processing'

                # Include all lines in the configuration block in the code output
                $null = $exampleCodeStringBuilder.AppendLine($exampleLine)
            }

            'ExampleCommentHeader'
            {
                Write-Debug -Message 'ExampleCommentHeader Block Processing'

                # Include all lines in Example Comment Header block except for headers
                $exampleLine = $exampleLine.TrimStart()

                if ($exampleLine -notin ('.SYNOPSIS', '.DESCRIPTION', '.EXAMPLE', '#>'))
                {
                    # Not a header so add this to the output
                    $null = $exampleDescriptionStringBuilder.AppendLine($exampleLine)
                }

                if ($exampleLine -eq '#>')
                {
                    Write-Debug -Message 'ExampleCommentHeader Block Ended'

                    # End of the Example Comment Header block
                    $blockType = [HelpExampleBlockType]::None
                }
            }

            default
            {
                Write-Debug -Message 'Not Currently Processing Block'

                # Check the current line
                if ($exampleLine.TrimStart() -eq '<#PSScriptInfo')
                {
                    Write-Debug -Message 'PSScriptInfo Block Started'

                    $blockType = [HelpExampleBlockType]::PSScriptInfo
                }
                elseif ($exampleLine -match 'Configuration')
                {
                    Write-Debug -Message 'Configuration Block Started'

                    $null = $exampleCodeStringBuilder.AppendLine($exampleLine)
                    $blockType = [HelpExampleBlockType]::Configuration
                }
                elseif ($exampleLine.TrimStart() -eq '<#')
                {
                    Write-Debug -Message 'ExampleCommentHeader Block Started'

                    $blockType = [HelpExampleBlockType]::ExampleCommentHeader
                }
            }
        }
    }

    # Assemble the final output
    $null = $exampleStringBuilder = New-Object -TypeName System.Text.StringBuilder
    $null = $exampleStringBuilder.AppendLine(".EXAMPLE $ExampleNumber")
    $null = $exampleStringBuilder.AppendLine()
    $null = $exampleStringBuilder.AppendLine($exampleDescriptionStringBuilder)
    $null = $exampleStringBuilder.Append($exampleCodeStringBuilder)

    # ALways return CRLF as line endings to work cross platform.
    return ($exampleStringBuilder.ToString() -replace '\r?\n', "`r`n")
}
#EndRegion './Private/Get-DscResourceHelpExampleContent.ps1' 142
#Region './Private/Get-DscResourceSchemaPropertyContent.ps1' 0
<#
    .SYNOPSIS
        Get-DscResourceSchemaPropertyContent is used to generate the parameter content
        for the wiki page.

    .DESCRIPTION
        Get-DscResourceSchemaPropertyContent is used to generate the parameter content
        for the wiki page.

    .PARAMETER Property
        A hash table with properties that is returned by Get-MofSchemaObject in
        the property Attributes.

    .PARAMETER UseMarkdown
        If certain text should be output as markdown, for example values of the
        hashtable property ValueMap.

    .EXAMPLE
        $content = Get-DscResourceSchemaPropertyContent -Property @(
                @{
                    Name = 'StringProperty'
                    DataType = 'String'
                    IsArray = $false
                    State = 'Key'
                    Description = 'Any description'
                    EmbeddedInstance = $null
                    ValueMap = $null
                }
            )

        Returns the parameter content based on the passed array of parameter metadata.
#>
function Get-DscResourceSchemaPropertyContent
{
    [CmdletBinding()]
    [OutputType([System.String[]])]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.Collections.Hashtable[]]
        $Property,

        [Parameter()]
        [System.Management.Automation.SwitchParameter]
        $UseMarkdown
    )

    $stringArray = [System.String[]] @()

    $stringArray += '| Parameter | Attribute | DataType | Description | Allowed Values |'
    $stringArray += '| --- | --- | --- | --- | --- |'

    foreach ($currentProperty in $Property)
    {
        if ($currentProperty.EmbeddedInstance -eq 'MSFT_Credential')
        {
            $dataType = 'PSCredential'
        }
        elseif (-not [System.String]::IsNullOrEmpty($currentProperty.EmbeddedInstance))
        {
            $dataType = $currentProperty.EmbeddedInstance
        }
        else
        {
            $dataType = $currentProperty.DataType
        }

        # If the attribute is an array, add [] to the DataType string.
        if ($currentProperty.IsArray)
        {
            $dataType = $dataType.ToString() + '[]'
        }

        $propertyLine = "| **$($currentProperty.Name)** " + `
            "| $($currentProperty.State) " + `
            "| $dataType |"

        if (-not [System.String]::IsNullOrEmpty($currentProperty.Description))
        {
            $propertyLine += ' ' + $currentProperty.Description
        }

        $propertyLine += ' |'

        if (-not [System.String]::IsNullOrEmpty($currentProperty.ValueMap))
        {
            $valueMap = $currentProperty.ValueMap

            if ($UseMarkdown.IsPresent)
            {
                $valueMap = $valueMap | ForEach-Object -Process {
                    '`{0}`' -f $_
                }
            }

            $propertyLine += ' ' + ($valueMap -join ', ')
        }

        $propertyLine += ' |'

        $stringArray += $propertyLine
    }

    return (, $stringArray)
}
#EndRegion './Private/Get-DscResourceSchemaPropertyContent.ps1' 106
#Region './Private/Get-DscResourceWikiExampleContent.ps1' 0
<#
    .SYNOPSIS
        This function reads an example file from a resource and converts
        it to markdown for inclusion in a resource wiki file.

    .DESCRIPTION
        The function will read the example PS1 file and convert the
        help header into the description text for the example. It will
        also surround the example configuration with code marks to
        indication it is powershell code.

    .PARAMETER ExamplePath
        The path to the example file.

    .PARAMETER ExampleNumber
        The (order) number of the example.

    .EXAMPLE
        Get-DscResourceWikiExampleContent -ExamplePath 'C:\repos\NetworkingDsc\Examples\Resources\DhcpClient\1-DhcpClient_EnableDHCP.ps1' -ExampleNumber 1

        Reads the content of 'C:\repos\NetworkingDsc\Examples\Resources\DhcpClient\1-DhcpClient_EnableDHCP.ps1'
        and converts it to markdown in preparation for being added to a resource wiki page.
#>

function Get-DscResourceWikiExampleContent
{
    [CmdletBinding()]
    [OutputType([System.String])]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.String]
        $ExamplePath,

        [Parameter(Mandatory = $true)]
        [System.Int32]
        $ExampleNumber
    )

    $exampleContent = Get-Content -Path $ExamplePath

    # Use a string builder to assemble the example description and code
    $exampleDescriptionStringBuilder = New-Object -TypeName System.Text.StringBuilder
    $exampleCodeStringBuilder = New-Object -TypeName System.Text.StringBuilder

    <#
        Step through each line in the source example and determine
        the content and act accordingly:
        \<#PSScriptInfo...#\> - Drop block
        \#Requires - Drop Line
        \<#...#\> - Drop .EXAMPLE, .SYNOPSIS and .DESCRIPTION but include all other lines
        Configuration ... - Include entire block until EOF
    #>
    $blockType = [WikiExampleBlockType]::None

    foreach ($exampleLine in $exampleContent)
    {
        Write-Debug -Message ('Processing Line: {0}' -f $exampleLine)

        # Determine the behavior based on the current block type
        switch ($blockType.ToString())
        {
            'PSScriptInfo'
            {
                Write-Debug -Message 'PSScriptInfo Block Processing'

                # Exclude PSScriptInfo block from any output
                if ($exampleLine -eq '#>')
                {
                    Write-Debug -Message 'PSScriptInfo Block Ended'

                    # End of the PSScriptInfo block
                    $blockType = [WikiExampleBlockType]::None
                }
            }

            'Configuration'
            {
                Write-Debug -Message 'Configuration Block Processing'

                # Include all lines in the configuration block in the code output
                $null = $exampleCodeStringBuilder.AppendLine($exampleLine)
            }

            'ExampleCommentHeader'
            {
                Write-Debug -Message 'ExampleCommentHeader Block Processing'

                # Include all lines in Example Comment Header block except for headers
                $exampleLine = $exampleLine.TrimStart()

                if ($exampleLine -notin ('.SYNOPSIS', '.DESCRIPTION', '.EXAMPLE', '#>'))
                {
                    # Not a header so add this to the output
                    $null = $exampleDescriptionStringBuilder.AppendLine($exampleLine)
                }

                if ($exampleLine -eq '#>')
                {
                    Write-Debug -Message 'ExampleCommentHeader Block Ended'

                    # End of the Example Comment Header block
                    $blockType = [WikiExampleBlockType]::None
                }
            }

            default
            {
                Write-Debug -Message 'Not Currently Processing Block'

                # Check the current line
                if ($exampleLine.TrimStart() -eq '<#PSScriptInfo')
                {
                    Write-Debug -Message 'PSScriptInfo Block Started'

                    $blockType = [WikiExampleBlockType]::PSScriptInfo
                }
                elseif ($exampleLine -match 'Configuration')
                {
                    Write-Debug -Message 'Configuration Block Started'

                    $null = $exampleCodeStringBuilder.AppendLine($exampleLine)
                    $blockType = [WikiExampleBlockType]::Configuration
                }
                elseif ($exampleLine.TrimStart() -eq '<#')
                {
                    Write-Debug -Message 'ExampleCommentHeader Block Started'

                    $blockType = [WikiExampleBlockType]::ExampleCommentHeader
                }
            }
        }
    }

    # Assemble the final output
    $null = $exampleStringBuilder = New-Object -TypeName System.Text.StringBuilder
    $null = $exampleStringBuilder.AppendLine("### Example $ExampleNumber")
    $null = $exampleStringBuilder.AppendLine()
    $null = $exampleStringBuilder.AppendLine($exampleDescriptionStringBuilder)
    $null = $exampleStringBuilder.AppendLine('```powershell')
    $null = $exampleStringBuilder.Append($exampleCodeStringBuilder)
    $null = $exampleStringBuilder.Append('```')

    # ALways return CRLF as line endings to work cross platform.
    return ($exampleStringBuilder.ToString() -replace '\r?\n', "`r`n")
}
#EndRegion './Private/Get-DscResourceWikiExampleContent.ps1' 147
#Region './Private/Get-MofSchemaObject.ps1' 0
<#
    .SYNOPSIS
        Get-MofSchemaObject is used to read a .schema.mof file for a DSC resource.

    .DESCRIPTION
        The Get-MofSchemaObject method is used to read the text content of the
        .schema.mof file that all MOF based DSC resources have. The object that
        is returned contains all of the data in the schema so it can be processed
        in other scripts.

    .PARAMETER FileName
        The full path to the .schema.mof file to process.

    .EXAMPLE
        $mof = Get-MofSchemaObject -FileName C:\repos\SharePointDsc\DSCRescoures\MSFT_SPSite\MSFT_SPSite.schema.mof

        This example parses a MOF schema file.

    .NOTES
        The function will thrown when run on MacOS because currently there is an
        issue using the type
        [Microsoft.PowerShell.DesiredStateConfiguration.Internal.DscClassCache]
        on macOS. See issue https://github.com/PowerShell/PowerShell/issues/5970
        and issue https://github.com/PowerShell/MMI/issues/33.
#>
function Get-MofSchemaObject
{
    [CmdletBinding()]
    [OutputType([System.Collections.Hashtable])]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.String]
        $FileName
    )

    if ($IsMacOS)
    {
        throw 'NotImplemented: Currently there is an issue using the type [Microsoft.PowerShell.DesiredStateConfiguration.Internal.DscClassCache] on macOS. See issue https://github.com/PowerShell/PowerShell/issues/5970 and issue https://github.com/PowerShell/MMI/issues/33.'
    }

    $temporaryPath = Get-TemporaryPath

    #region Workaround for OMI_BaseResource inheritance not resolving.

    $filePath = (Resolve-Path -Path $FileName).Path
    $tempFilePath = Join-Path -Path $temporaryPath -ChildPath "DscMofHelper_$((New-Guid).Guid).tmp"
    $rawContent = (Get-Content -Path $filePath -Raw) -replace '\s*:\s*OMI_BaseResource'

    Set-Content -LiteralPath $tempFilePath -Value $rawContent -ErrorAction 'Stop'

    # .NET methods don't like PowerShell drives
    $tempFilePath = Convert-Path -Path $tempFilePath

    #endregion

    try
    {
        $exceptionCollection = [System.Collections.ObjectModel.Collection[System.Exception]]::new()
        $moduleInfo = [System.Tuple]::Create('Module', [System.Version] '1.0.0')

        $class = [Microsoft.PowerShell.DesiredStateConfiguration.Internal.DscClassCache]::ImportClasses(
            $tempFilePath, $moduleInfo, $exceptionCollection
        )
    }
    catch
    {
        throw "Failed to import classes from file $FileName. Error $_"
    }
    finally
    {
        Remove-Item -LiteralPath $tempFilePath -Force
    }

    foreach ($currentCimClass in $class)
    {
        $attributes = foreach ($property in $currentCimClass.CimClassProperties)
        {
            $state = switch ($property.flags)
            {
                { $_ -band [Microsoft.Management.Infrastructure.CimFlags]::Key }
                {
                    'Key'
                }
                { $_ -band [Microsoft.Management.Infrastructure.CimFlags]::Required }
                {
                    'Required'
                }
                { $_ -band [Microsoft.Management.Infrastructure.CimFlags]::ReadOnly }
                {
                    'Read'
                }
                default
                {
                    'Write'
                }
            }

            @{
                Name             = $property.Name
                State            = $state
                DataType         = $property.CimType
                ValueMap         = $property.Qualifiers.Where( { $_.Name -eq 'ValueMap' }).Value
                IsArray          = $property.CimType -gt 16
                Description      = $property.Qualifiers.Where( { $_.Name -eq 'Description' }).Value
                EmbeddedInstance = $property.Qualifiers.Where( { $_.Name -eq 'EmbeddedInstance' }).Value
            }
        }

        @{
            ClassName    = $currentCimClass.CimClassName
            Attributes   = $attributes
            ClassVersion = $currentCimClass.CimClassQualifiers.Where( { $_.Name -eq 'ClassVersion' }).Value
            FriendlyName = $currentCimClass.CimClassQualifiers.Where( { $_.Name -eq 'FriendlyName' }).Value
        }
    }
}
#EndRegion './Private/Get-MofSchemaObject.ps1' 118
#Region './Private/Get-RegularExpressionParsedText.ps1' 0
<#
    .SYNOPSIS
        Get-RegularExpressionParsedText removes text that matches a regular expression.

    .DESCRIPTION
        Get-RegularExpressionParsedText removes text that matches a regular expression
        from the passed text string. A regular expression must conform to a specific
        grouping, see parameter 'RegularExpression' for more information.

    .PARAMETER Text
        The text string to process.

    .PARAMETER RegularExpression
        An array of regular expressions that should be used to parse the text. Each
        regular expression must be written so that the capture group 0 is the full
        match and the capture group 1 is the text that should be kept.

    .EXAMPLE
        $myText = Get-RegularExpressionParsedText -Text 'My code call `Get-Process`' -RegularExpression @('\`(.+?)\`')

        This example process the string an remove the inline code-block.
#>
function Get-RegularExpressionParsedText
{
    [CmdletBinding()]
    [OutputType([System.String])]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.String]
        $Text,

        [Parameter()]
        [System.String[]]
        $RegularExpression = @()
    )

    if ($RegularExpression.Count -gt 0)
    {
        foreach ($parseRegularExpression in $RegularExpression)
        {
            $allMatches = $Text | Select-String -Pattern $parseRegularExpression -AllMatches

            foreach ($regularExpressionMatch in $allMatches.Matches)
            {
                <#
                    Always assume the group 0 is the full match and
                    the group 1 contain what we should replace with.
                #>
                $Text = $Text -replace @(
                    [RegEx]::Escape($regularExpressionMatch.Groups[0].Value),
                    $regularExpressionMatch.Groups[1].Value
                )
            }
        }
    }

    return $Text
}
#EndRegion './Private/Get-RegularExpressionParsedText.ps1' 60
#Region './Private/Get-ResourceExampleAsMarkdown.ps1' 0
<#
    .SYNOPSIS
        Get-ResourceExampleAsMarkdown gathers all examples for a resource and returns
        them as string build object in markdown format.

    .DESCRIPTION
        Get-ResourceExampleAsMarkdown gathers all examples for a resource and returns
        them as string build object in markdown format.

    .PARAMETER Path
        The path to the source folder, the path will be recursively searched for *.ps1
        files. All found files will be assumed that they are examples and that
        documentation should be generated for them.

    .EXAMPLE
        $examplesMarkdown = Get-ResourceExampleAsMarkdown -Path 'c:\MyProject\source\Examples\Resources\MyResourceName'

        This example fetches all examples from the folder 'c:\MyProject\source\Examples\Resources\MyResourceName'
        and returns them as a single string in markdown format.
#>
function Get-ResourceExampleAsMarkdown
{
    [CmdletBinding()]
    [OutputType([System.Text.StringBuilder])]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.String]
        $Path
    )

    $filePath = Join-Path -Path $Path -ChildPath '*.ps1'

    $exampleFiles = @(Get-ChildItem -Path $filePath -File -Recurse -ErrorAction 'SilentlyContinue')

    if ($exampleFiles.Count -gt 0)
    {
        $outputExampleMarkDown = New-Object -TypeName 'System.Text.StringBuilder'

        Write-Verbose -Message ($script:localizedData.FoundResourceExamplesMessage -f $exampleFiles.Count)

        $null = $outputExampleMarkDown.AppendLine('## Examples')

        $exampleCount = 1

        foreach ($exampleFile in $exampleFiles)
        {
            $exampleContent = Get-DscResourceWikiExampleContent `
                -ExamplePath $exampleFile.FullName `
                -ExampleNumber ($exampleCount++)

            $null = $outputExampleMarkDown.AppendLine()
            $null = $outputExampleMarkDown.AppendLine($exampleContent)
        }
    }
    else
    {
        Write-Warning -Message ($script:localizedData.NoExampleFileFoundWarning)
    }

    return $outputExampleMarkDown
}
#EndRegion './Private/Get-ResourceExampleAsMarkdown.ps1' 63
#Region './Private/Get-ResourceExampleAsText.ps1' 0
<#
    .SYNOPSIS
        Get-ResourceExampleAsText gathers all examples for a resource and returns
        them as a string in a format that is used for conceptual help.

    .DESCRIPTION
        Get-ResourceExampleAsText gathers all examples for a resource and returns
        them as a string in a format that is used for conceptual help.

    .PARAMETER Path
        The path to the source folder, the path will be recursively searched for *.ps1
        files. All found files will be assumed that they are examples and that
        documentation should be generated for them.

    .EXAMPLE
        $examplesText = Get-ResourceExampleAsText -Path 'c:\MyProject\source\Examples\Resources\MyResourceName'

        This example fetches all examples from the folder 'c:\MyProject\source\Examples\Resources\MyResourceName'
        and returns them as a single string in a format that is used for conceptual help.
#>
function Get-ResourceExampleAsText
{
    [CmdletBinding()]
    [OutputType([System.Collections.Hashtable])]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.String]
        $Path
    )

    $filePath = Join-Path -Path $Path -ChildPath '*.ps1'

    $exampleFiles = @(Get-ChildItem -Path $filePath -File -Recurse -ErrorAction 'SilentlyContinue')

    if ($exampleFiles.Count -gt 0)
    {
        $exampleCount = 1

        Write-Verbose -Message ($script:localizedData.FoundResourceExamplesMessage -f $exampleFiles.Count)

        foreach ($exampleFile in $exampleFiles)
        {
            $exampleContent = Get-DscResourceHelpExampleContent `
                -ExamplePath $exampleFile.FullName `
                -ExampleNumber ($exampleCount++)

            $exampleContent = $exampleContent -replace '\r?\n', "`r`n"

            $text += $exampleContent
            $text += "`r`n"
        }
    }
    else
    {
        Write-Warning -Message ($script:localizedData.NoExampleFileFoundWarning)
    }

    return $text
}
#EndRegion './Private/Get-ResourceExampleAsText.ps1' 61
#Region './Private/Get-TemporaryPath.ps1' 0
<#
    .SYNOPSIS
        Get-TemporaryPath returns the temporary path for the OS.

    .DESCRIPTION
        The Get-TemporaryPath function will return the temporary
        path specific to the OS. It will return $ENV:Temp when run
        on Windows OS, '/tmp' when run in Linux and $ENV:TMPDIR when
        run on MacOS.

    .EXAMPLE
        Get-TemporaryPath

        Get the temporary path (which will differ between operating system).

    .NOTES
        We use Get-Variable to determine if the OS specific variables are
        defined so that we can mock these during testing. We also use Get-Item
        to get the environment variables so we can also mock these for testing.
#>

function Get-TemporaryPath
{
    [CmdletBinding()]
    [OutputType([System.String])]
    param ()

    $temporaryPath = $null

    switch ($true)
    {
        (-not (Test-Path -Path variable:IsWindows) -or ((Get-Variable -Name 'IsWindows' -ValueOnly -ErrorAction SilentlyContinue) -eq $true))
        {
            # Windows PowerShell or PowerShell 6+
            $temporaryPath = (Get-Item -Path env:TEMP).Value
        }

        ((Get-Variable -Name 'IsMacOs' -ValueOnly -ErrorAction SilentlyContinue) -eq $true)
        {
            $temporaryPath = (Get-Item -Path env:TMPDIR).Value
        }

        ((Get-Variable -Name 'IsLinux' -ValueOnly -ErrorAction SilentlyContinue) -eq $true)
        {
            $temporaryPath = '/tmp'
        }

        Default
        {
            throw 'Cannot set the temporary path. Unknown operating system.'
        }
    }

    return $temporaryPath
}
#EndRegion './Private/Get-TemporaryPath.ps1' 56
#Region './Private/New-DscClassResourceWikiPage.ps1' 0
<#
    .SYNOPSIS
        New-DscClassResourceWikiPage generates wiki pages for class-based resources
        that can be uploaded to GitHub to use as public documentation for a module.

    .DESCRIPTION
        The New-DscClassResourceWikiPage cmdlet will review all of the class-based and
        in a specified module directory and will output the Markdown files 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.

    .PARAMETER SourcePath
        The path to the root of the DSC resource module (where the PSD1 file is found,
        not the folder for and individual DSC resource).

    .PARAMETER BuiltModulePath
        The path to the root of the built DSC resource module, e.g.
        'output/MyResource/1.0.0'.

    .PARAMETER Force
        Overwrites any existing file when outputting the generated content.

    .EXAMPLE
        New-DscClassResourceWikiPage `
            -SourcePath C:\repos\MyResource\source `
            -BuiltModulePath C:\repos\MyResource\output\MyResource\1.0.0 `
            -OutputPath C:\repos\MyResource\output\WikiContent

        This example shows how to generate wiki documentation for a specific module.
#>
function New-DscClassResourceWikiPage
{
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '')]
    [CmdletBinding()]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.String]
        $OutputPath,

        [Parameter(Mandatory = $true)]
        [System.String]
        $SourcePath,

        [Parameter(Mandatory = $true)]
        [System.String]
        $BuiltModulePath,

        [Parameter()]
        [System.Management.Automation.SwitchParameter]
        $Force
    )

    if (Test-Path -Path $BuiltModulePath)
    {
        <#
            This must not use Recurse. Then it could potentially find resources
            that are part of common modules in the Modules folder.
        #>
        $getChildItemParameters = @{
            Path        = Join-Path -Path $BuiltModulePath -ChildPath '*'
            Include     = '*.psm1'
            ErrorAction = 'Stop'
            File        = $true
        }

        $builtModuleScriptFiles = Get-ChildItem @getChildItemParameters

        # Looping through each module file (normally just one).
        foreach ($builtModuleScriptFile in $builtModuleScriptFiles)
        {
            $dscResourceAsts = Get-ClassResourceAst -ScriptFile $builtModuleScriptFile.FullName

            Write-Verbose -Message ($script:localizedData.FoundClassBasedMessage -f $dscResourceAsts.Count, $builtModuleScriptFile.FullName)

            # Looping through each class-based resource.
            foreach ($dscResourceAst in $dscResourceAsts)
            {
                Write-Verbose -Message ($script:localizedData.GenerateWikiPageMessage -f $dscResourceAst.Name)

                $output = New-Object -TypeName 'System.Text.StringBuilder'

                $null = $output.AppendLine("# $($dscResourceAst.Name)")
                $null = $output.AppendLine()
                $null = $output.AppendLine('## Parameters')
                $null = $output.AppendLine()

                $sourceFilePath = Join-Path -Path $SourcePath -ChildPath ('Classes/*{0}.ps1' -f $dscResourceAst.Name)

                $className = @()

                if ($dscResourceAst.BaseTypes.Count -gt 0)
                {
                    $className += @($dscResourceAst.BaseTypes.TypeName.Name)
                }

                $className += $dscResourceAst.Name

                # Returns the properties for class and any existing parent class(es).
                $resourceProperty = Get-ClassResourceProperty -ClassName $className -SourcePath $SourcePath -BuiltModuleScriptFilePath $builtModuleScriptFile.FullName

                $propertyContent = Get-DscResourceSchemaPropertyContent -Property $resourceProperty -UseMarkdown

                foreach ($line in $propertyContent)
                {
                    $null = $output.AppendLine($line)
                }

                $null = $output.AppendLine()

                $dscResourceCommentBasedHelp = Get-CommentBasedHelp -Path $sourceFilePath

                $description = $dscResourceCommentBasedHelp.Description
                $description = $description -replace '[\r|\n]+$' # Removes all blank rows and whitespace at the end

                $null = $output.AppendLine('## Description')
                $null = $output.AppendLine()
                $null = $output.AppendLine($description)
                $null = $output.AppendLine()

                $examplesPath = Join-Path -Path $SourcePath -ChildPath ('Examples\Resources\{0}' -f $dscResourceAst.Name)

                $examplesOutput = Get-ResourceExampleAsMarkdown -Path $examplesPath

                if ($examplesOutput.Length -gt 0)
                {
                    $null = $output.Append($examplesOutput)
                }

                $outputFileName = '{0}.md' -f $dscResourceAst.Name

                $savePath = Join-Path -Path $OutputPath -ChildPath $outputFileName

                Write-Verbose -Message ($script:localizedData.OutputWikiPageMessage -f $savePath)

                $outputToWrite = $output.ToString()
                $outputToWrite = $outputToWrite -replace '[\r|\n]+$' # Removes all blank rows and whitespace at the end
                $outputToWrite = $outputToWrite -replace '\r?\n', "`r`n" # Normalize to CRLF
                $outputToWrite = $outputToWrite -replace '[ ]+\r\n', "`r`n" # Remove indentation from blank rows

                $null = Out-File `
                    -InputObject $outputToWrite `
                    -FilePath $savePath `
                    -Encoding utf8 `
                    -Force:$Force
            }
        }
    }
}
#EndRegion './Private/New-DscClassResourceWikiPage.ps1' 153
#Region './Private/New-DscMofResourceWikiPage.ps1' 0
<#
    .SYNOPSIS
        New-DscMofResourceWikiPage generates wiki pages for MOF-based resources
        that can be uploaded to GitHub to use as public documentation for a module.

    .DESCRIPTION
        The New-DscMofResourceWikiPage cmdlet will review all of the MOF-based and
        in a specified module directory and will output the Markdown files 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.

    .PARAMETER SourcePath
        The path to the root of the DSC resource module (where the PSD1 file is found,
        not the folder for and individual DSC resource).

    .PARAMETER BuiltModulePath
        The path to the root of the built DSC resource module, e.g.
        'output/MyResource/1.0.0'.

    .PARAMETER Force
        Overwrites any existing file when outputting the generated content.

    .EXAMPLE
        New-DscMofResourceWikiPage `
            -SourcePath C:\repos\MyResource\source `
            -BuiltModulePath C:\repos\MyResource\output\MyResource\1.0.0 `
            -OutputPath C:\repos\MyResource\output\WikiContent

        This example shows how to generate wiki documentation for a specific module.
#>
function New-DscMofResourceWikiPage
{
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSReviewUnusedParameter', '')]
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '')]
    [CmdletBinding()]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.String]
        $OutputPath,

        [Parameter(Mandatory = $true)]
        [System.String]
        $SourcePath,

        [Parameter(Mandatory = $true)]
        [System.String]
        $BuiltModulePath,

        [Parameter()]
        [System.Management.Automation.SwitchParameter]
        $Force
    )

    $mofSearchPath = Join-Path -Path $SourcePath -ChildPath '\**\*.schema.mof'
    $mofSchemaFiles = @(Get-ChildItem -Path $mofSearchPath -Recurse)

    Write-Verbose -Message ($script:localizedData.FoundMofFilesMessage -f $mofSchemaFiles.Count, $SourcePath)

    # Loop through all the Schema files found in the modules folder
    foreach ($mofSchemaFile in $mofSchemaFiles)
    {
        $mofSchemas = Get-MofSchemaObject -FileName $mofSchemaFile.FullName

        $dscResourceName = $mofSchemaFile.Name.Replace('.schema.mof', '')

        <#
            In a resource with one or more embedded instances (CIM classes) this
            will get the main resource CIM class.
        #>
        $resourceSchema = $mofSchemas |
            Where-Object -FilterScript {
                ($_.ClassName -eq $dscResourceName) -and ($null -ne $_.FriendlyName)
            }

        [System.Array] $readmeFile = Get-ChildItem -Path $mofSchemaFile.DirectoryName |
            Where-Object -FilterScript {
                $_.Name -like 'readme.md'
            }

        if ($readmeFile.Count -eq 1)
        {
            Write-Verbose -Message ($script:localizedData.GenerateWikiPageMessage -f $resourceSchema.FriendlyName)

            $output = New-Object -TypeName System.Text.StringBuilder

            $null = $output.AppendLine("# $($resourceSchema.FriendlyName)")
            $null = $output.AppendLine('')
            $null = $output.AppendLine('## Parameters')
            $null = $output.AppendLine('')

            $propertyContent = Get-DscResourceSchemaPropertyContent -Property $resourceSchema.Attributes -UseMarkdown

            foreach ($line in $propertyContent)
            {
                $null = $output.AppendLine($line)
            }

            <#
                In a resource with one or more embedded instances (CIM classes) this
                will get the embedded instances (CIM classes).
            #>
            $embeddedSchemas = $mofSchemas |
                Where-Object -FilterScript {
                    ($_.ClassName -ne $dscResourceName)
                }

            foreach ($embeddedSchema in $embeddedSchemas)
            {
                $null = $output.AppendLine()
                $null = $output.AppendLine("### $($embeddedSchema.ClassName)")
                $null = $output.AppendLine('')
                $null = $output.AppendLine('#### Parameters')
                $null = $output.AppendLine('')

                $propertyContent = Get-DscResourceSchemaPropertyContent -Property $embeddedSchema.Attributes -UseMarkdown

                foreach ($line in $propertyContent)
                {
                    $null = $output.AppendLine($line)
                }
            }

            $descriptionContent = Get-Content -Path $readmeFile.FullName -Raw

            # Change the description H1 header to an H2
            $descriptionContent = $descriptionContent -replace '# Description', '## Description'
            $null = $output.AppendLine()
            $null = $output.AppendLine($descriptionContent)

            $examplesPath = Join-Path -Path $SourcePath -ChildPath ('Examples\Resources\{0}' -f $resourceSchema.FriendlyName)

            $examplesOutput = Get-ResourceExampleAsMarkdown -Path $examplesPath

            if ($examplesOutput.Length -gt 0)
            {
                $null = $output.Append($examplesOutput)
            }

            $outputFileName = "$($resourceSchema.FriendlyName).md"
            $savePath = Join-Path -Path $OutputPath -ChildPath $outputFileName

            Write-Verbose -Message ($script:localizedData.OutputWikiPageMessage -f $savePath)

            $null = Out-File `
                -InputObject ($output.ToString() -replace '\r?\n', "`r`n") `
                -FilePath $savePath `
                -Encoding utf8 `
                -Force:$Force
        }
        elseif ($readmeFile.Count -gt 1)
        {
            Write-Warning -Message ($script:localizedData.MultipleDescriptionFileFoundWarning -f $resourceSchema.FriendlyName, $readmeFile.Count)
        }
        else
        {
            Write-Warning -Message ($script:localizedData.NoDescriptionFileFoundWarning -f $resourceSchema.FriendlyName)
        }
    }
}
#EndRegion './Private/New-DscMofResourceWikiPage.ps1' 164
#Region './Private/New-TempFolder.ps1' 0
<#
    .SYNOPSIS
        Creates a new temporary folder with a random name.

    .DESCRIPTION
        Creates a new temporary folder with a random name.

    .EXAMPLE
        New-TempFolder

        This command creates a new temporary folder with a random name.

    .PARAMETER MaximumRetries
        Specifies the maximum number of time to retry creating the temp folder.

    .OUTPUTS
        System.IO.DirectoryInfo
#>
function New-TempFolder
{
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '')]
    [CmdletBinding()]
    [OutputType([System.IO.DirectoryInfo])]
    param
    (
        [Parameter()]
        [System.Int32]
        $MaximumRetries = 10
    )

    $tempPath = [System.IO.Path]::GetTempPath()

    $retries = 0

    do
    {
        $retries++

        if ($retries -gt $MaximumRetries)
        {
            throw ($localizedData.NewTempFolderCreationError -f $tempPath)
        }

        $name = [System.IO.Path]::GetRandomFileName()

        $path = New-Item -Path $tempPath -Name $name -ItemType Directory -ErrorAction SilentlyContinue
    } while (-not $path)

    return $path
}
#EndRegion './Private/New-TempFolder.ps1' 51
#Region './Private/New-WikiFooter.ps1' 0
<#
    .SYNOPSIS
        Creates the Wiki footer file if one does not already exist.

    .DESCRIPTION
        Creates the Wiki footer file if one does not already exist.

    .PARAMETER Path
        The path for the Wiki footer file.

    .PARAMETER BaseName
        The base name of the Wiki footer file. Defaults to '_Footer.md'.

    .EXAMPLE
        New-WikiFooter -Path $path

        Creates the Wiki footer.
#>
function New-WikiFooter
{
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '')]
    [CmdletBinding()]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.String]
        $Path,

        [Parameter()]
        [System.String]
        $BaseName = '_Footer.md'
    )

    $wikiFooterPath = Join-Path -Path $path -ChildPath $BaseName

    if (-not (Test-Path -Path $wikiFooterPath))
    {
        Write-Verbose -Message ($localizedData.GenerateWikiFooterMessage -f $BaseName)

        $wikiFooter = @()

        Out-File -InputObject $wikiFooter -FilePath $wikiFooterPath -Encoding 'ascii'
    }
}
#EndRegion './Private/New-WikiFooter.ps1' 45
#Region './Private/New-WikiSidebar.ps1' 0
<#
    .SYNOPSIS
        Creates the Wiki side bar file from the list of markdown files in the path.

    .DESCRIPTION
        Creates the Wiki side bar file from the list of markdown files in the path.

    .PARAMETER ModuleName
        The name of the module to generate a new Wiki Sidebar file for.

    .PARAMETER Path
        The path to both create the Wiki Sidebar file and where to find the
        markdown files that was generated by New-DscResourceWikiPage, e.g.
        '.\output\WikiContent'.

    .PARAMETER BaseName
        The base name of the Wiki Sidebar file. Defaults to '_Sidebar.md'.

    .EXAMPLE
        New-WikiSidebar -ModuleName 'ActiveDirectoryDsc -Path '.\output\WikiContent'

        Creates the Wiki side bar from the list of markdown files in the path.
#>
function New-WikiSidebar
{
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '')]
    [CmdletBinding()]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.String]
        $ModuleName,

        [Parameter(Mandatory = $true)]
        [System.String]
        $Path,

        [Parameter()]
        [System.String]
        $BaseName = '_Sidebar.md'
    )

    $wikiSideBarPath = Join-Path -Path $Path -ChildPath $BaseName

    Write-Verbose -Message ($localizedData.GenerateWikiSidebarMessage -f $BaseName)

    $WikiSidebarContent = @(
        "# $ModuleName Module"
        ' '
    )

    $wikiFiles = Get-ChildItem -Path (Join-Path -Path $Path -ChildPath '*.md') -Exclude '_*.md'

    foreach ($file in $wikiFiles)
    {
        Write-Verbose -Message ("`t{0}" -f ($localizedData.AddFileToSideBar -f $file.Name))

        $WikiSidebarContent += "- [$($file.BaseName)]($($file.BaseName))"
    }

    Out-File -InputObject $WikiSidebarContent -FilePath $wikiSideBarPath -Encoding 'ascii'
}
#EndRegion './Private/New-WikiSidebar.ps1' 63
#Region './Private/Task.Generate_Conceptual_Help.ps1' 0
<#
    .SYNOPSIS
        This is the alias to the build task Generate_Conceptual_Help's script file.

    .DESCRIPTION
        This makes available the alias 'Task.Generate_Conceptual_Help' that is
        exported in the module manifest so that the build task can be correctly
        imported using for example Invoke-Build.

    .NOTES
        This is using the pattern lined out in the Invoke-Build repository
        https://github.com/nightroman/Invoke-Build/tree/master/Tasks/Import.
#>

Set-Alias -Name 'Task.Generate_Conceptual_Help' -Value "$PSScriptRoot/tasks/Generate_Conceptual_Help.build.ps1"
#EndRegion './Private/Task.Generate_Conceptual_Help.ps1' 16
#Region './Private/Task.Generate_Wiki_Content.ps1' 0
<#
    .SYNOPSIS
        This is the alias to the build task Generate_Wiki_Content's script file.

    .DESCRIPTION
        This makes available the alias 'Task.Generate_Wiki_Content' that is
        exported in the module manifest so that the build task can be correctly
        imported using for example Invoke-Build.

    .NOTES
        This is using the pattern lined out in the Invoke-Build repository
        https://github.com/nightroman/Invoke-Build/tree/master/Tasks/Import.
#>

Set-Alias -Name 'Task.Generate_Wiki_Content' -Value "$PSScriptRoot/tasks/Generate_Wiki_Content.build.ps1"
#EndRegion './Private/Task.Generate_Wiki_Content.ps1' 16
#Region './Private/Task.Publish_GitHub_Wiki_Content.ps1' 0
<#
    .SYNOPSIS
        This is the alias to the build task Publish_GitHub_Wiki_Content's script file.

    .DESCRIPTION
        This makes available the alias 'Task.Publish_GitHub_Wiki_Content' that is
        exported in the module manifest so that the build task can be correctly
        imported using for example Invoke-Build.

    .NOTES
        This is using the pattern lined out in the Invoke-Build repository
        https://github.com/nightroman/Invoke-Build/tree/master/Tasks/Import.
#>

Set-Alias -Name 'Task.Publish_GitHub_Wiki_Content' -Value "$PSScriptRoot/tasks/Publish_GitHub_Wiki_Content.build.ps1"
#EndRegion './Private/Task.Publish_GitHub_Wiki_Content.ps1' 16
#Region './Private/Test-PropertyMemberAst.ps1' 0
<#
    .SYNOPSIS
        This function returns the property state value of an class-based DSC
        resource property.

    .DESCRIPTION
        This function returns the property state value of an DSC class-based
        resource property.

    .PARAMETER Ast
        The Abstract Syntax Tree (AST) for class-based DSC resource property.
        The passed value must be an AST of the type 'PropertyMemberAst'.

    .PARAMETER IsKey
        Specifies if the parameter is expected to have the type qualifier Key.

    .PARAMETER IsMandatory
        Specifies if the parameter is expected to have the type qualifier Mandatory.

    .PARAMETER IsWrite
        Specifies if the parameter is expected to have the type qualifier Write.

    .PARAMETER IsRead
        Specifies if the parameter is expected to have the type qualifier Read.

    .EXAMPLE
        Test-PropertyMemberAst -IsKey -Ast {
            [DscResource()]
            class NameOfResource {
                [DscProperty(Key)]
                [string] $KeyName

                [NameOfResource] Get() {
                    return $this
                }

                [void] Set() {}

                [bool] Test() {
                    return $true
                }
            }
        }.Ast.Find({$args[0] -is [System.Management.Automation.Language.PropertyMemberAst]}, $false)

        Returns $true that the property 'KeyName' is Key.
#>
function Test-PropertyMemberAst
{
    [CmdletBinding()]
    [OutputType([System.Boolean])]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.Management.Automation.Language.PropertyMemberAst]
        $Ast,

        [Parameter(Mandatory = $true, ParameterSetName = 'IsKey')]
        [System.Management.Automation.SwitchParameter]
        $IsKey,

        [Parameter(Mandatory = $true, ParameterSetName = 'IsMandatory')]
        [System.Management.Automation.SwitchParameter]
        $IsMandatory,

        [Parameter(Mandatory = $true, ParameterSetName = 'IsWrite')]
        [System.Management.Automation.SwitchParameter]
        $IsWrite,

        [Parameter(Mandatory = $true, ParameterSetName = 'IsRead')]
        [System.Management.Automation.SwitchParameter]
        $IsRead
    )

    $astFilter = {
        $args[0] -is [System.Management.Automation.Language.NamedAttributeArgumentAst]
    }

    $propertyNamedAttributeArgumentAsts = $Ast.FindAll($astFilter, $true)

    if ($IsKey.IsPresent -and 'Key' -in $propertyNamedAttributeArgumentAsts.ArgumentName)
    {
        return $true
    }

    # Having Key on a property makes it implicitly Mandatory.
    if ($IsMandatory.IsPresent -and $propertyNamedAttributeArgumentAsts.ArgumentName -in @('Mandatory', 'Key'))
    {
        return $true
    }

    if ($IsRead.IsPresent -and 'NotConfigurable' -in $propertyNamedAttributeArgumentAsts.ArgumentName)
    {
        return $true
    }

    if ($IsWrite.IsPresent -and $propertyNamedAttributeArgumentAsts.ArgumentName -notin @('Key', 'Mandatory', 'NotConfigurable'))
    {
        return $true
    }

    return $false
}
#EndRegion './Private/Test-PropertyMemberAst.ps1' 103
#Region './Public/Invoke-Git.ps1' 0
<#
    .SYNOPSIS
        Invokes a git command.

    .DESCRIPTION
        Invokes a git command with command line arguments using System.Diagnostics.Process.

    .PARAMETER WorkingDirectory
        The path to the git working directory.

    .PARAMETER Timeout
        Seconds to wait for process to exit.

    .PARAMETER Arguments
        The arguments to pass to the Git executable.

    .EXAMPLE
        Invoke-Git -WorkingDirectory 'C:\SomeDirectory' -Arguments @( 'clone', 'https://github.com/X-Guardian/xActiveDirectory.wiki.git', '--quiet' )

        Invokes the Git executable to clone the specified repository to the working directory.

    .EXAMPLE
        Invoke-Git -WorkingDirectory 'C:\SomeDirectory' -Arguments @( 'status' ) -TimeOut 10

        Invokes the Git executable to return the status while having a 10 second timeout.
#>

function Invoke-Git
{
    [CmdletBinding()]
    [OutputType([System.Collections.Hashtable])]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.String]
        $WorkingDirectory,

        [Parameter(Mandatory = $false)]
        [System.Int32]
        $TimeOut = 120,

        [Parameter(ValueFromRemainingArguments = $true)]
        [System.String[]]
        $Arguments
    )

    $returnValue = @{
        'ExitCode'       = -1
        'StandardOutput' = ''
        'StandardError'  = ''
    }

    $argumentsJoined = $Arguments -join ' '

    # Trying to remove any access token from the debug output.
    if ($argumentsJoined -match ':[\d|a-f].*@')
    {
        $argumentsJoined = $argumentsJoined -replace ':[\d|a-f].*@', ':RedactedToken@'
    }

    Write-Debug -Message ($localizedData.InvokingGitMessage -f $argumentsJoined)

    try
    {
        $process = New-Object -TypeName System.Diagnostics.Process
        $process.StartInfo.Arguments = $Arguments
        $process.StartInfo.CreateNoWindow = $true
        $process.StartInfo.FileName = 'git.exe'
        $process.StartInfo.RedirectStandardOutput = $true
        $process.StartInfo.RedirectStandardError = $true
        $process.StartInfo.UseShellExecute = $false
        $process.StartInfo.WindowStyle = [System.Diagnostics.ProcessWindowStyle]::Hidden
        $process.StartInfo.WorkingDirectory = $WorkingDirectory

        if ($process.Start() -eq $true)
        {
            if ($process.WaitForExit($TimeOut) -eq $true)
            {
                $returnValue.ExitCode = $process.ExitCode
                $returnValue.StandardOutput = $process.StandardOutput.ReadToEnd()
                $returnValue.StandardError = $process.StandardError.ReadToEnd()
            }
        }
    }
    catch
    {
        throw $_
    }
    finally
    {
        if ($process)
        {
            $process.Dispose()
        }
    }

    return $returnValue
}
#EndRegion './Public/Invoke-Git.ps1' 99
#Region './Public/New-DscResourcePowerShellHelp.ps1' 0
<#
    .SYNOPSIS
        New-DscResourcePowerShellHelp generates PowerShell compatible help files
        for a DSC resource module.

    .DESCRIPTION
        The New-DscResourcePowerShellHelp generates PowerShell compatible help files
        for a DSC resource module.

        The command will review all of the MOF-based and class-based resources in a
        specified module directory and will inject PowerShell help files for each
        resource. These help files include details on the property types for each
        resource, as well as a text description and examples where they exist.

        The help files are output to the OutputPath directory if specified. If not,
        they are output to the relevant resource's 'en-US' directory either in the
        path set by 'ModulePath' or to 'DestinationModulePath' if set.

        For MOF-based resources a README.md with a text description must exist in
        the resource's subdirectory for the help file to be generated. For class-based
        resources each DscResource should have their own file in the Classes folder
        (using the template of the Sampler project).

        To get examples added to the conceptual help the examples must be present
        in an individual resource example folder, e.g.
        'Examples/Resources/<ResourceName>/1-Example.ps1'. Prefixing the value
        with a number will sort the examples in that order.

        Example directory structure:

            Examples
                \---Resources
                    \---MyResourceName
                            1-FirstExample.ps1
                            2-SecondExample.ps1
                            3-ThirdExample.ps1

        These help files can then be read by passing the name of the resource as a
        parameter to Get-Help.

    .PARAMETER ModulePath
        The path to the root of the DSC resource module where the PSD1 file is
        found, for example the folder 'source'. If there are MOF-based resources
        there should be a 'DSCResources' child folder in this path. If using
        class-based resources there should be a 'Classes' child folder in this path.

    .PARAMETER DestinationModulePath
        The destination module path can be used to set the path where module is
        built before being deployed. This must be set to the root of the built
        module, e.g 'c:\repos\ModuleName\output\ModuleName\1.0.0'.

        The conceptual help file will be saved in this path. For MOF-based resources
        it will be saved to the 'en-US' folder that is inside in either the 'DSCResources'
        or 'DSCClassResources' folder (if using that pattern for class-based resources).

        When using the pattern with having all powershell classes in the same
        module script file (.psm1) and all class-based resource are found in that
        file (not using 'DSCClassResources'). This path will be used to find the
        built module when generating conceptual help for class-based resource.
        It will also be used to save the conceptual help to the built modules
        'en-US' folder.

        If OutputPath is assigned that will be used for saving the output instead.

    .PARAMETER OutputPath
        The output path can be used to set the path where all the generated files
        will be saved (all files to the same path).

    .PARAMETER MarkdownCodeRegularExpression
        An array of regular expressions that should be used to parse the text of
        the synopsis, description and parameter descriptions. Each regular expression
        must be written so that the capture group 0 is the full match and the capture
        group 1 is the text that should be kept. This is meant to be used to remove
        markdown code, but it can be used for anything as it follow the previous
        mention pattern for the regular expression sequence.

    .PARAMETER Force
        When set the to $true and existing conceptual help file will be overwritten.

    .EXAMPLE
        New-DscResourcePowerShellHelp -ModulePath C:\repos\SharePointDsc

        This example shows how to generate help for a specific module

    .EXAMPLE
        New-DscResourcePowerShellHelp -ModulePath C:\repos\SharePointDsc -DestinationModulePath C:\repos\SharePointDsc\output\SharePointDsc\1.0.0

        This example shows how to generate help for a specific module and output
        the result to a built module.

    .EXAMPLE
        New-DscResourcePowerShellHelp -ModulePath C:\repos\SharePointDsc -OutputPath C:\repos\SharePointDsc\en-US

        This example shows how to generate help for a specific module and output
        all the generated files to the same output path.

    .NOTES
        Line endings are hard-coded to CRLF to handle different platforms similar.
#>
function New-DscResourcePowerShellHelp
{
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '')]
    [CmdletBinding()]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.String]
        $ModulePath,

        [Parameter()]
        [System.String]
        $DestinationModulePath,

        [Parameter()]
        [System.String]
        $OutputPath,

        [Parameter()]
        [System.String[]]
        $MarkdownCodeRegularExpression = @(),

        [Parameter()]
        [System.Management.Automation.SwitchParameter]
        $Force
    )

    #region MOF-based resource
    $mofSearchPath = Join-Path -Path $ModulePath -ChildPath '\**\*.schema.mof'
    $mofSchemas = @(Get-ChildItem -Path $mofSearchPath -Recurse)

    Write-Verbose -Message ($script:localizedData.FoundMofFilesMessage -f $mofSchemas.Count, $ModulePath)

    foreach ($mofSchema in $mofSchemas)
    {
        $result = (Get-MofSchemaObject -FileName $mofSchema.FullName) | Where-Object -FilterScript {
            ($_.ClassName -eq $mofSchema.Name.Replace('.schema.mof', '')) `
                -and ($null -ne $_.FriendlyName)
        }

        # This is a workaround for issue #42.
        $readMeFile = Get-ChildItem -Path $mofSchema.DirectoryName -ErrorAction 'SilentlyContinue' |
            Where-Object -FilterScript {
                $_.Name -like 'readme.md'
            }

        if ($readMeFile)
        {
            $descriptionPath = $readMeFile.FullName

            Write-Verbose -Message ($script:localizedData.GenerateHelpDocumentMessage -f $result.FriendlyName)

            $output = ".NAME`r`n"
            $output += " $($result.FriendlyName)"
            $output += "`r`n`r`n"

            $descriptionContent = Get-Content -Path $descriptionPath -Raw
            $descriptionContent = $descriptionContent -replace '\r?\n', "`r`n"

            $descriptionContent = $descriptionContent -replace '\r\n', "`r`n "
            $descriptionContent = $descriptionContent -replace '# Description\r\n ', ".DESCRIPTION"
            $descriptionContent = $descriptionContent -replace '\r\n\s{4}\r\n', "`r`n`r`n"
            $descriptionContent = $descriptionContent -replace '\s{4}$', ''

            if (-not [System.String]::IsNullOrEmpty($descriptionContent))
            {
                $descriptionContent = Get-RegularExpressionParsedText -Text $descriptionContent -RegularExpression $MarkdownCodeRegularExpression
            }

            $output += $descriptionContent
            $output += "`r`n"

            foreach ($property in $result.Attributes)
            {
                $output += ".PARAMETER $($property.Name)`r`n"
                $output += " $($property.State) - $($property.DataType)"
                $output += "`r`n"

                if ([string]::IsNullOrEmpty($property.ValueMap) -ne $true)
                {
                    $output += " Allowed values: "

                    $property.ValueMap | ForEach-Object {
                        $output += $_ + ", "
                    }

                    $output = $output.TrimEnd(" ")
                    $output = $output.TrimEnd(",")
                    $output += "`r`n"
                }

                if (-not [System.String]::IsNullOrEmpty($property.Description))
                {
                    $propertyDescription = Get-RegularExpressionParsedText -Text $property.Description -RegularExpression $MarkdownCodeRegularExpression
                }

                $output += " {0}" -f $propertyDescription
                $output += "`r`n`r`n"
            }

            $resourceExamplePath = Join-Path -Path $ModulePath -ChildPath ('Examples\Resources\{0}' -f $result.FriendlyName)

            $exampleContent = Get-ResourceExampleAsText -Path $resourceExamplePath

            $output += $exampleContent

            # Trim excessive blank lines and indents at the end.
            $output = $output -replace '[\r|\n|\s]+$', "`r`n"

            $outputFileName = "about_$($result.FriendlyName).help.txt"

            if ($PSBoundParameters.ContainsKey('OutputPath'))
            {
                # Output to $OutputPath if specified.
                $savePath = Join-Path -Path $OutputPath -ChildPath $outputFileName
            }
            elseif ($PSBoundParameters.ContainsKey('DestinationModulePath'))
            {
                # Output to the resource 'en-US' directory in the DestinationModulePath.
                $null = $mofSchema.DirectoryName -match '(.+)(DSCResources|DSCClassResources)(.+)'
                $resourceRelativePath = $matches[3]
                $dscRootFolderName = $matches[2]

                $savePath = Join-Path -Path $DestinationModulePath -ChildPath $dscRootFolderName |
                    Join-Path -ChildPath $resourceRelativePath |
                        Join-Path -ChildPath 'en-US' |
                            Join-Path -ChildPath $outputFileName
            }
            else
            {
                # Output to the resource 'en-US' directory in the ModulePath.
                $savePath = Join-Path -Path $mofSchema.DirectoryName -ChildPath 'en-US' |
                    Join-Path -ChildPath $outputFileName
            }

            Write-Verbose -Message ($script:localizedData.OutputHelpDocumentMessage -f $savePath)

            $output | Out-File -FilePath $savePath -Encoding 'ascii' -Force:$Force
        }
        else
        {
            Write-Warning -Message ($script:localizedData.NoDescriptionFileFoundWarning -f $result.FriendlyName)
        }
    }
    #endregion MOF-based resource

    #region Class-based resource
    if (-not [System.String]::IsNullOrEmpty($DestinationModulePath) -and (Test-Path -Path $DestinationModulePath))
    {
        <#
            This must not use Recurse. Then it could potentially find resources
            that are part of common modules in the Modules folder.
        #>
        $getChildItemParameters = @{
            Path        = Join-Path -Path $DestinationModulePath -ChildPath '*'
            Include     = '*.psm1'
            ErrorAction = 'Stop'
            File        = $true
        }

        $builtModuleScriptFiles = Get-ChildItem @getChildItemParameters

        # Looping through each module file (normally just one).
        foreach ($builtModuleScriptFile in $builtModuleScriptFiles)
        {
            $tokens, $parseErrors = $null

            $ast = [System.Management.Automation.Language.Parser]::ParseFile($builtModuleScriptFile.FullName, [ref] $tokens, [ref] $parseErrors)

            if ($parseErrors)
            {
                throw $parseErrors
            }

            $astFilter = {
                $args[0] -is [System.Management.Automation.Language.TypeDefinitionAst] `
                    -and $args[0].IsClass -eq $true `
                    -and $args[0].Attributes.Extent.Text -imatch '\[DscResource\(.*\)\]'
            }

            $dscResourceAsts = $ast.FindAll($astFilter, $true)

            Write-Verbose -Message ($script:localizedData.FoundClassBasedMessage -f $dscResourceAsts.Count, $builtModuleScriptFile.FullName)

            # Looping through each class-based resource.
            foreach ($dscResourceAst in $dscResourceAsts)
            {
                Write-Verbose -Message ($script:localizedData.GenerateHelpDocumentMessage -f $dscResourceAst.Name)

                $sourceFilePath = Join-Path -Path $ModulePath -ChildPath ('Classes/*{0}.ps1' -f $dscResourceAst.Name)

                $dscResourceCommentBasedHelp = Get-CommentBasedHelp -Path $sourceFilePath

                $synopsis = $dscResourceCommentBasedHelp.Synopsis
                $synopsis = $synopsis -replace '[\r|\n]+$' # Removes all blank rows at the end
                $synopsis = $synopsis -replace '\r?\n', "`r`n" # Normalize to CRLF
                $synopsis = $synopsis -replace '\r\n', "`r`n " # Indent all rows
                $synopsis = $synopsis -replace '[ ]+\r\n', "`r`n" # Remove indentation from blank rows

                $description = $dscResourceCommentBasedHelp.Description
                $description = $description -replace '[\r|\n]+$' # Removes all blank rows and whitespace at the end
                $description = $description -replace '\r?\n', "`r`n" # Normalize to CRLF
                $description = $description -replace '\r\n', "`r`n " # Indent all rows
                $description = $description -replace '[ ]+\r\n', "`r`n" # Remove indentation from blank rows

                $output = ".NAME`r`n"
                $output += ' {0}' -f $dscResourceAst.Name
                $output += "`r`n`r`n"
                $output += ".SYNOPSIS`r`n"

                if (-not [System.String]::IsNullOrEmpty($synopsis))
                {
                    $synopsis = Get-RegularExpressionParsedText -Text $synopsis -RegularExpression $MarkdownCodeRegularExpression

                    $output += ' {0}' -f $synopsis
                }

                $output += "`r`n`r`n"
                $output += ".DESCRIPTION`r`n"

                if (-not [System.String]::IsNullOrEmpty($description))
                {
                    $description = Get-RegularExpressionParsedText -Text $description -RegularExpression $MarkdownCodeRegularExpression

                    $output += ' {0}' -f $description
                }

                $output += "`r`n`r`n"

                $astFilter = {
                    $args[0] -is [System.Management.Automation.Language.PropertyMemberAst]
                }

                $propertyMemberAsts = $dscResourceAst.FindAll($astFilter, $true)

                # Looping through each resource property.
                foreach ($propertyMemberAst in $propertyMemberAsts)
                {
                    Write-Verbose -Message ($script:localizedData.FoundClassResourcePropertyMessage -f $propertyMemberAst.Name, $dscResourceAst.Name)

                    $propertyState = Get-ClassResourcePropertyState -Ast $propertyMemberAst

                    $output += ".PARAMETER {0}`r`n" -f $propertyMemberAst.Name
                    $output += ' {0} - {1}' -f $propertyState, $propertyMemberAst.PropertyType.TypeName.FullName
                    $output += "`r`n"

                    $astFilter = {
                        $args[0] -is [System.Management.Automation.Language.AttributeAst] `
                            -and $args[0].TypeName.Name -eq 'ValidateSet'
                    }

                    $propertyAttributeAsts = $propertyMemberAst.FindAll($astFilter, $true)

                    if ($propertyAttributeAsts)
                    {
                        $output += " Allowed values: {0}" -f ($propertyAttributeAsts.PositionalArguments.Value -join ', ')
                        $output += "`r`n"
                    }

                    # The key name must be upper-case for it to match the right item in the list of parameters.
                    $propertyDescription = ($dscResourceCommentBasedHelp.Parameters[$propertyMemberAst.Name.ToUpper()] -replace '[\r|\n]+$')

                    $propertyDescription = $propertyDescription -replace '[\r|\n]+$' # Removes all blank rows at the end
                    $propertyDescription = $propertyDescription -replace '\r?\n', "`r`n" # Normalize to CRLF
                    $propertyDescription = $propertyDescription -replace '\r\n', "`r`n " # Indent all rows
                    $propertyDescription = $propertyDescription -replace '[ ]+\r\n', "`r`n" # Remove indentation from blank rows

                    if (-not [System.String]::IsNullOrEmpty($propertyDescription))
                    {
                        $propertyDescription = Get-RegularExpressionParsedText -Text $propertyDescription -RegularExpression $MarkdownCodeRegularExpression

                        $output += " {0}" -f $propertyDescription
                        $output += "`r`n"
                    }

                    $output += "`r`n"
                }

                $examplesPath = Join-Path -Path $ModulePath -ChildPath ('Examples\Resources\{0}' -f $dscResourceAst.Name)

                $exampleContent = Get-ResourceExampleAsText -Path $examplesPath

                $output += $exampleContent

                # Trim excessive blank lines and indents at the end, then insert a last blank line.
                $output = $output -replace '[\r?\n|\s]+$', "`r`n"

                $outputFileName = 'about_{0}.help.txt' -f $dscResourceAst.Name

                if ($PSBoundParameters.ContainsKey('OutputPath'))
                {
                    # Output to $OutputPath if specified.
                    $savePath = Join-Path -Path $OutputPath -ChildPath $outputFileName
                }
                else
                {
                    # Output to the built modules en-US folder.
                    $savePath = Join-Path -Path $DestinationModulePath -ChildPath 'en-US' |
                        Join-Path -ChildPath $outputFileName
                }

                Write-Verbose -Message ($script:localizedData.OutputHelpDocumentMessage -f $savePath)

                $output | Out-File -FilePath $savePath -Encoding 'ascii' -NoNewLine -Force:$Force
            }
        }
    }
    #endregion Class-based resource
}
#EndRegion './Public/New-DscResourcePowerShellHelp.ps1' 409
#Region './Public/New-DscResourceWikiPage.ps1' 0
<#
    .SYNOPSIS
        New-DscResourceWikiPage generates wiki pages that can be uploaded to GitHub
        to use as public documentation for a module.

    .DESCRIPTION
        The New-DscResourceWikiPage cmdlet will review all of the MOF-based and
        class-based resources in a specified module directory and will output the
        Markdown files 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.

    .PARAMETER SourcePath
        The path to the root of the DSC resource module (where the PSD1 file is found,
        not the folder for and individual DSC resource).

    .PARAMETER BuiltModulePath
        The path to the root of the built DSC resource module, e.g.
        'output/MyResource/1.0.0'.

    .PARAMETER Force
        Overwrites any existing file when outputting the generated content.

    .EXAMPLE
        New-DscResourceWikiPage `
            -SourcePath C:\repos\MyResource\source `
            -BuiltModulePath C:\repos\MyResource\output\MyResource\1.0.0 `
            -OutputPath C:\repos\MyResource\output\WikiContent

        This example shows how to generate wiki documentation for a specific module.
#>
function New-DscResourceWikiPage
{
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '')]
    [CmdletBinding()]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.String]
        $OutputPath,

        [Parameter(Mandatory = $true)]
        [System.String]
        $SourcePath,

        [Parameter(Mandatory = $true)]
        [System.String]
        $BuiltModulePath,

        [Parameter()]
        [System.Management.Automation.SwitchParameter]
        $Force
    )

    New-DscMofResourceWikiPage @PSBoundParameters

    New-DscClassResourceWikiPage @PSBoundParameters
}
#EndRegion './Public/New-DscResourceWikiPage.ps1' 62
#Region './Public/Publish-WikiContent.ps1' 0
<#
    .SYNOPSIS
        Publishes the Wiki Content that is generated by New-DscResourceWikiPage.

    .DESCRIPTION
        This function publishes the content pages from the Wiki Content that is
        generated by New-DscResourceWikiPage along with any additional files
        stored in the 'WikiSource' directory of the repository and an auto-generated
        sidebar file containing links to all the markdown files to the Wiki of a
        specified GitHub repository.

    .PARAMETER Path
        The path to the output that was generated by New-DscResourceWikiPage.

    .PARAMETER OwnerName
        The owner name of the Github repository.

    .PARAMETER RepositoryName
        The name of the Github repository.

    .PARAMETER ModuleName
        The name of the Dsc Resource Module.

    .PARAMETER ModuleVersion
        The build version number to tag the Wiki Github commit with.

    .PARAMETER GitHubAccessToken
        The GitHub access token to allow a push to the GitHub Wiki.

    .PARAMETER GitUserEmail
        The email address to use for the Git commit.

    .PARAMETER GitUserName
        The user name to use for the Git commit.

    .PARAMETER GlobalCoreAutoCrLf
        Specifies how line breaks should be handled when cloning the
        GitHub wiki repository. Valid values are 'true', 'false', or
        'input'.

    .EXAMPLE
        Publish-WikiContent `
            -Path '.\output\WikiContent' `
            -OwnerName 'dsccommunity' `
            -RepositoryName 'SqlServerDsc' `
            -ModuleName 'SqlServerDsc' `
            -ModuleVersion '14.0.0' `
            -GitHubAccessToken 'token' `
            -GitUserEmail 'email@contoso.com' `
            -GitUserName 'dsc' `
            -WikiSourcePath '.\source\WikiSource'

        Adds the content pages in '.\output\WikiContent' to the Wiki for the
        specified GitHub repository.
#>
function Publish-WikiContent
{
    [CmdletBinding()]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.String]
        $Path,

        [Parameter(Mandatory = $true)]
        [System.String]
        $OwnerName,

        [Parameter(Mandatory = $true)]
        [System.String]
        $RepositoryName,

        [Parameter(Mandatory = $true)]
        [System.String]
        $ModuleName,

        [Parameter(Mandatory = $true)]
        [System.String]
        $ModuleVersion,

        [Parameter(Mandatory = $true)]
        [System.String]
        $GitHubAccessToken,

        [Parameter(Mandatory = $true)]
        [System.String]
        $GitUserEmail,

        [Parameter(Mandatory = $true)]
        [System.String]
        $GitUserName,

        [Parameter()]
        [ValidateSet('true', 'false', 'input')]
        [System.String]
        $GlobalCoreAutoCrLf
    )

    $ErrorActionPreference = 'Stop'

    Write-Verbose -Message $script:localizedData.CreateTempDirMessage

    $tempPath = New-TempFolder
    $wikiRepoName = "https://github.com/$OwnerName/$RepositoryName.wiki.git"

    try
    {
        Write-Verbose -Message $script:localizedData.ConfigGlobalGitMessage

        if ($PSBoundParameters.ContainsKey('GlobalCoreAutoCrLf'))
        {
            $null = Invoke-Git -WorkingDirectory $tempPath.FullName `
                        -Arguments @( 'config', '--global', 'core.autocrlf', $GlobalCoreAutoCrLf )
        }

        Write-Verbose -Message ($script:localizedData.CloneWikiGitRepoMessage -f $WikiRepoName)

        $gitCloneResult = Invoke-Git -WorkingDirectory $tempPath.FullName `
                            -Arguments @( 'clone', $wikiRepoName, $tempPath, '--quiet' )

        if ($gitCloneResult.ExitCode -eq 0)
        {
            $copyWikiFileParameters = @{
                Path            = $Path
                DestinationPath = $tempPath
                Force           = $true
            }

            Copy-WikiFolder @copyWikiFileParameters

            New-WikiSidebar -ModuleName $ModuleName -Path $tempPath
            New-WikiFooter -Path $tempPath

            Set-Location -Path $tempPath

            Write-Verbose -Message $script:localizedData.ConfigLocalGitMessage

            $null = Invoke-Git -WorkingDirectory $tempPath.FullName `
                        -Arguments @( 'config', '--local', 'user.email', $GitUserEmail )

            $null = Invoke-Git -WorkingDirectory $tempPath.FullName `
                        -Arguments @( 'config', '--local', 'user.name', $GitUserName )

            $null = Invoke-Git -WorkingDirectory $tempPath.FullName `
                        -Arguments @( 'remote', 'set-url', 'origin', "https://$($GitUserName):$($GitHubAccessToken)@github.com/$OwnerName/$RepositoryName.wiki.git" )

            Write-Verbose -Message $localizedData.AddWikiContentToGitRepoMessage

            $null = Invoke-Git -WorkingDirectory $tempPath.FullName `
                        -Arguments @( 'add', '*' )

            Write-Verbose -Message ($localizedData.CommitAndTagRepoChangesMessage -f $ModuleVersion)

            $gitCommitResult = Invoke-Git -WorkingDirectory $tempPath.FullName `
                                    -Arguments @( 'commit', '--message', "`"$($localizedData.UpdateWikiCommitMessage -f $ModuleVersion)`"", '--quiet' )

            if ($gitCommitResult.ExitCode -eq 0)
            {
                $null = Invoke-Git -WorkingDirectory $tempPath.FullName `
                            -Arguments @( 'tag', '--annotate', $ModuleVersion, '--message', $ModuleVersion )

                Write-Verbose -Message $localizedData.PushUpdatedRepoMessage

                $null = Invoke-Git -WorkingDirectory $tempPath.FullName `
                            -Arguments @( 'push', 'origin', '--quiet' )

                $null = Invoke-Git -WorkingDirectory $tempPath.FullName `
                            -Arguments @( 'push', 'origin', $ModuleVersion, '--quiet' )

                Write-Verbose -Message $localizedData.PublishWikiContentCompleteMessage
            }
            else
            {
                Write-Warning -Message $localizedData.NothingToCommitToWiki
            }
        }
        else
        {
            Write-Verbose -Message $script:localizedData.WikiGitCloneFailMessage

            Write-Debug -Message ($script:localizedData.WikiGitCloneFailMessageDebug -f $wikiRepoName)
            Write-Debug -Message ($script:localizedData.InvokeGitStandardOutput -f $gitCloneResult.StandardOutput)
            Write-Debug -Message ($script:localizedData.InvokeGitStandardError -f $gitCloneResult.StandardError)
            Write-Debug -Message ($script:localizedData.InvokeGitExitCodeMessage -f $gitCloneResult.ExitCode)
        }
    }
    finally
    {
        Remove-Item -Path $tempPath -Recurse -Force
    }
}
#EndRegion './Public/Publish-WikiContent.ps1' 192
#Region './Public/Set-WikiModuleVersion.ps1' 0
<#
    .SYNOPSIS
        Sets the module version in a markdown file.

    .DESCRIPTION
        Sets the module version in a markdown file. Parses the markdown file for
        #.#.# which is replaced by the specified module version.

    .PARAMETER Path
        The path to a markdown file to set the module version in.

    .PARAMETER ModuleVersion
        The base name of the Wiki Sidebar file. Defaults to '_Sidebar.md'.

    .EXAMPLE
        Set-WikiModuleVersion -Path '.\output\WikiContent\Home.md' -ModuleVersion '14.0.0'

        Replaces '#.#.#' with the module version '14.0.0' in the markdown file 'Home.md'.
#>
function Set-WikiModuleVersion
{
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '')]
    [CmdletBinding()]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.String]
        $Path,

        [Parameter(Mandatory = $true)]
        [System.String]
        $ModuleVersion
    )

    $markdownContent = Get-Content -Path $path -Raw

    $markdownContent = $markdownContent -replace '#\.#\.#', $ModuleVersion

    Out-File -InputObject $markdownContent -FilePath $Path -Encoding 'ascii' -NoNewline
}
#EndRegion './Public/Set-WikiModuleVersion.ps1' 41
#Region './Public/Split-ModuleVersion.ps1' 0
<#
    .SYNOPSIS
        This function parses a module version string as returns a PSCustomObject
        which each of the module version's parts.

    .DESCRIPTION
        This function parses a module version string as returns a PSCustomObject
        which each of the module version's parts.

    .PARAMETER ModuleVersion
        The module version for which to return the module version's parts.

    .EXAMPLE
        Split-ModuleVersion -ModuleVersion '1.15.0-pr0224-0022+Sha.47ae45eb'

        Splits the module version an returns a PSCustomObject with the parts
        of the module version.

        Version PreReleaseString ModuleVersion
        ------- ---------------- -------------
        1.15.0 pr0224 1.15.0-pr0224

    .NOTES
        This is required by the function Get-BuiltModuleVersion and the build task
        Generate_Wiki_Content.
#>
function Split-ModuleVersion
{
    [CmdletBinding()]
    [OutputType([System.Management.Automation.PSCustomObject])]
    param
    (
        [Parameter()]
        [System.String]
        $ModuleVersion
    )

    <#
        This handles a previous version of the module that suggested to pass
        a version string with metadata in the CI pipeline that can look like
        this: 1.15.0-pr0224-0022+Sha.47ae45eb2cfed02b249f239a7c55e5c71b26ab76.Date.2020-01-07
    #>
    $ModuleVersion = ($ModuleVersion -split '\+', 2)[0]

    $moduleVersion, $preReleaseString = $ModuleVersion -split '-', 2

    <#
        The cmldet Publish-Module does not yet support semver compliant
        pre-release strings. If the prerelease string contains a dash ('-')
        then the dash and everything behind is removed. For example
        'pr54-0012' is parsed to 'ps54'.
    #>
    $validPreReleaseString, $preReleaseStringSuffix = $preReleaseString -split '-'

    if ($validPreReleaseString)
    {
        $fullModuleVersion = $moduleVersion + '-' + $validPreReleaseString
    }
    else
    {
        $fullModuleVersion = $moduleVersion
    }

    $moduleVersionParts = [PSCustomObject] @{
        Version          = $moduleVersion
        PreReleaseString = $validPreReleaseString
        ModuleVersion    = $fullModuleVersion
    }

    return $moduleVersionParts
}
#EndRegion './Public/Split-ModuleVersion.ps1' 72