DscResource.DocGenerator

0.12.0-preview0004

DscResource.DocGenerator.psm1

#Region './prefix.ps1' -1

# 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' -1

<#
    .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 Force
        If present, copies files forcefully, overwriting any existing files.

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

        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 ($script:localizedData.CopyWikiFoldersMessage -f ($Path -join ''', '''))

    $wikiFiles = Get-ChildItem -Recurse -Path $Path

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

        if ($file.DirectoryName -eq $Path)
        {
            $destination = $DestinationPath
        }
        else
        {
            $destination = Join-Path -Path $DestinationPath -ChildPath ($file.DirectoryName -replace [regex]::Escape($Path), '')
        }

        Copy-Item -Path $file.FullName -Destination $destination -Force:$Force
    }
}
#EndRegion './Private/Copy-WikiFolder.ps1' 62
#Region './Private/Format-Text.ps1' -1

<#
    .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' -1

<#
    .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' -1

<#
    .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' -1

<#
    .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)

        <#
            Skip if the class's source file does not exist. Thi can happen if the
            class uses a parent class from a different module.
        #>
        if (-not (Test-Path -Path $sourceFilePath))
        {
            continue
        }

        $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' 140
#Region './Private/Get-ClassResourcePropertyState.ps1' -1

<#
    .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' -1

<#
    .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.

        GetHelpContent() only works for script comment-based help, which requires the
        comment-based help to be the first element in the file and have two blank lines
        after the comment-based help block. To avoid this limitation the comment-based
        help block is parsed out of the source file and made into a ScriptBlockAst that
        is used to get the comment-based help using GetHelpContent().

#>
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

    $regexOptions = [System.Text.RegularExpressions.RegexOptions]::Multiline
    $firstCommentBlockStart = [System.Text.RegularExpressions.Regex]::Match($scriptContent, '^<#', $regexOptions)
    $firstCommentBlockEnd = [System.Text.RegularExpressions.Regex]::Match($scriptContent, '#>', $regexOptions)

    # Ensure the comment-based help block start at the top of the file.
    if ($firstCommentBlockStart.Success -and $firstCommentBlockEnd.Success)
    {
        Write-Verbose -Message ($script:localizedData.ParsingOutCommentBasedHelpBlock -f $Path)

        if ($firstCommentBlockStart.Index -ne 0)
        {
            Write-Debug -Message ($script:localizedData.CommentBasedHelpBlockNotAtTopMessage -f $Path)
        }

        # Parsing out only the comment-based help block.
        $scriptContent = $scriptContent.Substring($firstCommentBlockStart.Index, $firstCommentBlockEnd.Index + $firstCommentBlockEnd.Length)
    }
    else
    {
        Write-Verbose -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' 103
#Region './Private/Get-CompositeResourceParameterState.ps1' -1

<#
    .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' -1

<#
    .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-CompositeResourceSchemaPropertyContent.ps1' -1

<#
    .SYNOPSIS
        Get-CompositeResourceSchemaPropertyContent is used to generate the parameter content
        for the wiki page.

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

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

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

    .EXAMPLE
        $content = Get-CompositeResourceSchemaPropertyContent -Property @(
                @{
                    Name = 'StringProperty'
                    State = 'Required'
                    Type = 'String'
                    ValidateSet = @('Value1','Value2')
                    Description = 'Any description'
                }
            )

        Returns the parameter content based on the passed array of parameter metadata.
#>
function Get-CompositeResourceSchemaPropertyContent
{
    [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)
    {
        $propertyLine = "| **$($currentProperty.Name)** " + `
            "| $($currentProperty.State) " + `
            "| $($currentProperty.Type) |"

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

        $propertyLine += ' |'

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

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

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

        $propertyLine += ' |'

        $stringArray += $propertyLine
    }

    return (, $stringArray)
}
#EndRegion './Private/Get-CompositeResourceSchemaPropertyContent.ps1' 85
#Region './Private/Get-CompositeSchemaObject.ps1' -1

<#
    .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()

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

        @{
            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' 86
#Region './Private/Get-ConfigurationAst.ps1' -1

<#
    .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' -1

<#
    .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' -1

<#
    .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' -1

<#
    .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' -1

<#
    .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' -1

<#
    .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' -1

<#
    .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' -1

<#
    .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' -1

<#
    .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/Hide-GitToken.ps1' -1

<#
    .SYNOPSIS
        Redacts token from Invoke-Git command.

    .DESCRIPTION
        Redacts the token from the specified git command so that the command can be safely outputted in logs.

    .PARAMETER Command
        Command passed to Invoke-Git

    .EXAMPLE
        Hide-GitToken -Command @( 'remote', 'add', 'origin', 'https://user:1b7270718ad84857b52941b36a632f369d18ff72@github.com/Owner/Repo.git' )

        Returns a string to be used for logs.
#>

function Hide-GitToken
{
    [CmdletBinding()]
    [OutputType([System.String])]
    param
    (
        [Parameter(Mandatory=$true)]
        [System.String[]]
        $Command
    )

    [System.String] $returnValue = $Command -join ' '

    [System.String] $returnValue = $returnValue -replace "gh(p|o|u|s|r)_([A-Za-z0-9]{1,251})",'**REDACTED-TOKEN**'

    [System.String] $returnValue = $returnValue -replace "[0-9a-f]{40}",'**REDACTED-TOKEN**'

    return $returnValue
}
#EndRegion './Private/Hide-GitToken.ps1' 36
#Region './Private/New-DscClassResourceWikiPage.ps1' -1

<#
    .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 Metadata
        Specifies metadata that is added to the markdown file.

    .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.

    .EXAMPLE
        New-DscClassResourceWikiPage `
            -SourcePath C:\repos\MyResource\source `
            -BuiltModulePath C:\repos\MyResource\output\MyResource\1.0.0 `
            -OutputPath C:\repos\MyResource\output\WikiContent `
            -Metadata @{
                Type = 'ClassResource'
                Category = 'Class-based resources'
            }

        This example shows how to generate wiki documentation for a specific module
        and passing in metadata for the markdown files.
#>
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.Collections.Hashtable]
        $Metadata,

        [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'

                # Add metadata to the top of the file.
                if ($Metadata)
                {
                    $null = $output.AppendLine('---')

                    foreach ($key in ($Metadata.Keys | Sort-Object))
                    {
                        $null = $output.AppendLine("$($key): $($Metadata.$key)")
                    }

                    $null = $output.AppendLine('---')
                    $null = $output.AppendLine()
                }

                # Add the documentation for the resource.
                $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' 188
#Region './Private/New-DscCompositeResourceWikiPage.ps1' -1

<#
    .SYNOPSIS
        New-DscCompositeResourceWikiPage generates wiki pages for composite resources
        that can be uploaded to GitHub to use as public documentation for a module.

    .DESCRIPTION
        The New-DscCompositeResourceWikiPage cmdlet will review all of the composite 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 Metadata
        Specifies metadata that is added to the markdown file.

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

    .EXAMPLE
        New-DscCompositeResourceWikiPage `
            -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.

    .EXAMPLE
        New-DscCompositeResourceWikiPage `
            -SourcePath C:\repos\MyResource\source `
            -BuiltModulePath C:\repos\MyResource\output\MyResource\1.0.0 `
            -OutputPath C:\repos\MyResource\output\WikiContent `
            -Metadata @{
                Type = 'CompositeResource'
                Category = 'Composites resources'
            }

        This example shows how to generate wiki documentation for a specific module
        and passing in metadata for the markdown files.
#>
function New-DscCompositeResourceWikiPage
{
    [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.Collections.Hashtable]
        $Metadata,

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

    $compositeSearchPath = Join-Path -Path $SourcePath -ChildPath '\**\*.schema.psm1'
    $compositeSchemaFiles = @(Get-ChildItem -Path $compositeSearchPath -Recurse)

    Write-Verbose -Message ($script:localizedData.FoundCompositeFilesMessage -f $compositeSchemaFiles.Count, $SourcePath)

    # Loop through all the Schema files found in the modules folder
    foreach ($compositeSchemaFile in $compositeSchemaFiles)
    {
        $compositeSchemaObject = Get-CompositeSchemaObject -FileName $compositeSchemaFile.FullName

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

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

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

            # Add metadata to the top of the file.
            if ($Metadata)
            {
                $null = $output.AppendLine('---')

                foreach ($key in ($Metadata.Keys | Sort-Object))
                {
                    $null = $output.AppendLine("$($key): $($Metadata.$key)")
                }

                $null = $output.AppendLine('---')
                $null = $output.AppendLine()
            }

            # Add the documentation for the resource.
            $null = $output.AppendLine("# $($compositeSchemaObject.Name)")
            $null = $output.AppendLine('')
            $null = $output.AppendLine('## Parameters')
            $null = $output.AppendLine('')

            $propertyContent = Get-CompositeResourceSchemaPropertyContent -Property $compositeSchemaObject.Parameters -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 $compositeSchemaObject.Name)

            $examplesOutput = Get-ResourceExampleAsMarkdown -Path $examplesPath

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

            $outputFileName = "$($compositeSchemaObject.Name).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 $compositeSchemaObject.Name, $readmeFile.Count)
        }
        else
        {
            Write-Warning -Message ($script:localizedData.NoDescriptionFileFoundWarning -f $compositeSchemaObject.Name)
        }
    }
}
#EndRegion './Private/New-DscCompositeResourceWikiPage.ps1' 163
#Region './Private/New-DscMofResourceWikiPage.ps1' -1

<#
    .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 Metadata
        Specifies metadata that is added to the markdown file.

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

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

        This example shows how to generate wiki documentation for a specific module.

    .EXAMPLE
        New-DscMofResourceWikiPage `
            -SourcePath C:\repos\MyResource\source `
            -OutputPath C:\repos\MyResource\output\WikiContent `
            -Metadata @{
                Type = 'MofResource'
                Category = 'MOF-based resources'
            }

        This example shows how to generate wiki documentation for a specific module
        and passing in metadata for the markdown files.
#>
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()]
        [System.Collections.Hashtable]
        $Metadata,

        [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

            # Add metadata to the top of the file.
            if ($Metadata)
            {
                $null = $output.AppendLine('---')

                foreach ($key in ($Metadata.Keys | Sort-Object))
                {
                    $null = $output.AppendLine("$($key): $($Metadata.$key)")
                }

                $null = $output.AppendLine('---')
                $null = $output.AppendLine()
            }

            # Add the documentation for the resource.
            $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' 189
#Region './Private/New-TempFolder.ps1' -1

<#
    .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 ($script: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' -1

<#
    .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 OutputPath
        The path in which the Wiki footer file should be generated.

    .PARAMETER WikiSourcePath
        The path in which the code should check for an existing 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]
        $OutputPath,

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

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

    $wikiFooterOutputPath = Join-Path -Path $OutputPath -ChildPath $BaseName
    $wikiFooterWikiSourcePath = Join-Path -Path $WikiSourcePath -ChildPath $BaseName

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

        $wikiFooter = @()

        Out-File -InputObject $wikiFooter -FilePath $wikiFooterOutputPath -Encoding 'ascii'
    }
}
#EndRegion './Private/New-WikiFooter.ps1' 53
#Region './Private/New-WikiSidebar.ps1' -1

<#
    .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 OutputPath
        The path in which to create the Wiki Sidebar file, e.g. '.\output\WikiContent'.


    .PARAMETER WikiSourcePath
        The path 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]
        $OutputPath,

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

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

    $wikiSideBarOutputPath = Join-Path -Path $OutputPath -ChildPath $BaseName
    $wikiSideBarWikiSourcePath = Join-Path -Path $WikiSourcePath -ChildPath $BaseName

    if (-not (Test-Path -Path $wikiSideBarWikiSourcePath))
    {
        Write-Verbose -Message ($script:localizedData.GenerateWikiSidebarMessage -f $BaseName)

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

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

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

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

        Out-File -InputObject $WikiSidebarContent -FilePath $wikiSideBarOutputPath -Encoding 'ascii'
    }
}
#EndRegion './Private/New-WikiSidebar.ps1' 74
#Region './Private/Out-GitResult.ps1' -1

<#
    .SYNOPSIS
        Shows return object from Invoke-Git.

    .DESCRIPTION
        When Invoke-Git returns a non-zero exit code, this function shows the result.

    .PARAMETER ExitCode
        ExitCode returned from running git command.

    .PARAMETER StandardOutput
        Standard Output returned from running git command.

    .PARAMETER StandardError
        Standard Error returned from running git command.

    .PARAMETER Command
        Command arguments passed to git.

    .PARAMETER WorkingDirectory
        Working Directory used when running git command.

    .EXAMPLE
        $splatParameters = @{
            'ExitCode' = 128
            'StandardOutput' = 'StandardOutput-128'
            'StandardError' = 'StandardError-128'
            'Command' = 'commit --message "some message"'
            'WorkingDirectory' = 'C:\some\path\'
        }

        Out-GitResult @splatParameters

        Shows the Invoke-Git result of a commit.

    .NOTES
        $NULL values are allowed since string formatter `-f` will convert it to an
        empty string before Write-Verbose/Write-Debug process `-Message`.
#>

function Out-GitResult
{
    [CmdletBinding()]
    [OutputType()]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.Int32]
        $ExitCode,

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

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

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

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

    switch ($Command[0].ToUpper())
    {
        'CLONE'
                {
                    if ($ExitCode -eq 128)
                    {
                        Write-Verbose -Message $script:localizedData.WikiGitCloneFailMessage
                    }
                }
        'COMMIT'
                {
                    if ($ExitCode -eq 1)
                    {
                        Write-Verbose -Message $script:localizedData.NothingToCommitToWiki
                    }
                }
    }

    Write-Verbose -Message ($script:localizedData.InvokeGitStandardOutputMessage -f $StandardOutput)
    Write-Verbose -Message ($script:localizedData.InvokeGitStandardErrorMessage -f $StandardError)
    Write-Verbose -Message ($script:localizedData.InvokeGitExitCodeMessage -f $ExitCode)

    Write-Debug -Message ($script:localizedData.InvokeGitCommandDebug -f $(Hide-GitToken -Command $Command))
    Write-Debug -Message ($script:localizedData.InvokeGitWorkingDirectoryDebug -f $WorkingDirectory)
}
#EndRegion './Private/Out-GitResult.ps1' 93
#Region './Private/Remove-EscapedMarkdownCode.ps1' -1

<#
    .SYNOPSIS
        Removes a escaped markdown code from a Markdown file.

    .DESCRIPTION
        The Remove-EscapedMarkdownCode function removes escaped markdown code
        from a Markdown file. It searches for the escaped sequences and removes
        it from the file.

    .PARAMETER FilePath
        Specifies the path to the Markdown file.

    .EXAMPLE
        Remove-EscapedMarkdownCode -FilePath 'C:\Path\To\File.md'

        Removes found escaped sequences from the Markdown file located at "C:\Path\To\File.md".

    .INPUTS
        [System.IO.FileInfo]
        Accepts a FileInfo object representing the Markdown file.

    .OUTPUTS
        None. The function modifies the content of the Markdown file directly.
#>
function Remove-EscapedMarkdownCode
{
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '', Justification = 'This function is a private helper function and is not exported publicly.')]
    [CmdletBinding()]
    param
    (
        [Parameter(Mandatory = $true, ValueFromPipeline = $true)]
        [ValidateScript({Test-Path $_ -PathType 'Leaf'})]
        [System.IO.FileInfo]
        $FilePath
    )

    process
    {
        $content = Get-Content -Path $FilePath.FullName -Raw

        $escapedPatterns = @(
            @{
                RegularExpression = '\\\`(.+?)\\\`' # Remove escaped inline code-blocks
                Replacement = '`$1`'
            }
            @{
                RegularExpression = '\\\[(.+?)\\\]' # Remove escaped links
                Replacement = '[$1]'
            }

            @{
                RegularExpression = '(?m)^\\\>' # Remove quoted blocks
                Replacement = '>'
            }
        )

        foreach ($pattern in $escapedPatterns)
        {
            $content = $content -replace $pattern.RegularExpression, $pattern.Replacement
        }

        # Write the updated content back to the file.
        Set-Content -Path $FilePath.FullName -Value $content
    }
}
#EndRegion './Private/Remove-EscapedMarkdownCode.ps1' 66
#Region './Private/Remove-ParameterFromMarkdown.ps1' -1

<#
    .SYNOPSIS
        Removes a parameter from a Markdown file.

    .DESCRIPTION
        The Remove-ParameterFromMarkdown function removes a specified parameter
        from a Markdown file. It searches for the parameter block identified by
        the given parameter name and removes it from the file.

    .PARAMETER FilePath
        Specifies the path to the Markdown file.

    .PARAMETER ParameterName
        Specifies the name of the parameter to be removed.

    .EXAMPLE
        Remove-ParameterFromMarkdown -FilePath 'C:\Path\To\File.md' -ParameterName 'MyParameter'

        Removes the parameter named "MyParameter" from the Markdown file located at "C:\Path\To\File.md".

    .INPUTS
        [System.IO.FileInfo]
        Accepts a FileInfo object representing the Markdown file.

    .OUTPUTS
        None. The function modifies the content of the Markdown file directly.
#>
function Remove-ParameterFromMarkdown
{
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '', Justification = 'This function is a private helper function and is not exported publicly.')]
    [CmdletBinding()]
    param
    (
        [Parameter(Mandatory = $true, ValueFromPipeline = $true)]
        [ValidateScript({Test-Path $_ -PathType 'Leaf'})]
        [System.IO.FileInfo]
        $FilePath,

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

    process
    {
        $content = Get-Content -Path $FilePath.FullName -Raw

        if (-not ($ParameterName.StartsWith('-')))
        {
            $ParameterName = ('-{0}' -f $ParameterName)
        }

        $patternParameterSection = "### $ParameterName\r?\n[\S\s\r\n]*?(?=#{2,3}?)"
        $patternSyntaxSection = "\[?$ParameterName <\w+>\]? ?"

        $regex = [regex]::new($patternParameterSection, [System.Text.RegularExpressions.RegexOptions]::Multiline)

        $parameters = $regex.Matches($content)

        if ($parameters.Count -gt 0)
        {
            # process the parameter
            Write-Verbose ('Removing parameter {0} from {1}' -f $ParameterName, $FilePath.BaseName)

            # Remove the parameter section from the content.
            $content = $content -replace $patternParameterSection

            # Remove the parameter from the syntax section.
            $content = $content -replace $patternSyntaxSection

            # Write the updated content back to the file.
            Set-Content -Path $FilePath.FullName -Value $content
        }
        else
        {
            Write-Verbose ('No parameter nodes matching {0} found in {1}' -f $ParameterName, $FilePath.BaseName)
        }
    }
}
#EndRegion './Private/Remove-ParameterFromMarkdown.ps1' 80
#Region './Private/Task.Clean_Markdown_Metadata.build.ps1' -1

<#
    .SYNOPSIS
        This is the alias to the build task Clean_Markdown_Metadata script file.

    .DESCRIPTION
        This makes available the alias 'Task.Clean_Markdown_Metadata' 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.Clean_Markdown_Metadata' -Value "$PSScriptRoot/tasks/Clean_Markdown_Metadata.build.ps1"
#EndRegion './Private/Task.Clean_Markdown_Metadata.build.ps1' 16
#Region './Private/Task.Clean_Markdown_Of_Public_Commands.build.ps1' -1

<#
    .SYNOPSIS
        This is the alias to the build task Clean_Markdown_Of_Public_Commands script file.

    .DESCRIPTION
        This makes available the alias 'Task.Clean_Markdown_Of_Public_Commands' 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.Clean_Markdown_Of_Public_Commands' -Value "$PSScriptRoot/tasks/Clean_Markdown_Of_Public_Commands.build.ps1"
#EndRegion './Private/Task.Clean_Markdown_Of_Public_Commands.build.ps1' 16
#Region './Private/Task.Generate_Conceptual_Help.ps1' -1

<#
    .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_External_Help_File_For_Public_Commands.ps1' -1

<#
    .SYNOPSIS
        This is the alias to the build task Generate_External_Help_File_For_Public_Commands script file.

    .DESCRIPTION
        This makes available the alias 'Task.Generate_External_Help_File_For_Public_Commands' 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_External_Help_File_For_Public_Commands' -Value "$PSScriptRoot/tasks/Generate_External_Help_File_For_Public_Commands.build.ps1"
#EndRegion './Private/Task.Generate_External_Help_File_For_Public_Commands.ps1' 16
#Region './Private/Task.Generate_Markdown_For_Public_Commands.build.ps1' -1

<#
    .SYNOPSIS
        This is the alias to the build task Generate_Markdown_For_Public_Commands script file.

    .DESCRIPTION
        This makes available the alias 'Task.Generate_Markdown_For_Public_Commands' 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_Markdown_For_Public_Commands' -Value "$PSScriptRoot/tasks/Generate_Markdown_For_Public_Commands.build.ps1"
#EndRegion './Private/Task.Generate_Markdown_For_Public_Commands.build.ps1' 16
#Region './Private/Task.Generate_Wiki_Content.ps1' -1

<#
    .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.Generate_Wiki_Sidebar.ps1' -1

<#
    .SYNOPSIS
        This is the alias to the build task Generate_Wiki_Sidebar's script file.

    .DESCRIPTION
        This makes available the alias 'Task.Generate_Wiki_Sidebar' 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_Sidebar' -Value "$PSScriptRoot/tasks/Generate_Wiki_Sidebar.build.ps1"
#EndRegion './Private/Task.Generate_Wiki_Sidebar.ps1' 16
#Region './Private/Task.Publish_GitHub_Wiki_Content.ps1' -1

<#
    .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' -1

<#
    .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/Add-NewLine.ps1' -1

<#
    .SYNOPSIS
        Adds a new line at the end of a file.

    .DESCRIPTION
        The Add-NewLineAtEndOfFile function adds a new line at the end of the specified file.

    .PARAMETER FileInfo
        Specifies the file to which the new line will be added.

    .PARAMETER AtEndOfFile
        Specifies that the new line should be added to the end of the file.

    .EXAMPLE
        Add-NewLineAtEndOfFile -FileInfo "C:\path\to\file.txt" -AtEndOfFile

        Adds a new line at the end of the file located at "C:\path\to\file.txt" without prompting for confirmation.

    .INPUTS
        [System.IO.FileInfo]

        Accepts a FileInfo object representing the file to which the new line will be added.

    .OUTPUTS
        None. The function does not generate any output.
#>
function Add-NewLine
{
    [CmdletBinding()]
    param
    (

        [Parameter(ValueFromPipeline = $true, Mandatory = $true, ParameterSetName = 'AtEndOfFile')]
        [System.IO.FileInfo]
        $FileInfo,

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

    process
    {
        $fileContent = Get-Content -Path $FileInfo.FullName -Raw

        if ($AtEndOfFile.IsPresent)
        {
            $fileContent += "`r`n"
        }

        [System.IO.File]::WriteAllText($FileInfo.FullName, $fileContent)
    }
}
#EndRegion './Public/Add-NewLine.ps1' 54
#Region './Public/Edit-CommandDocumentation.ps1' -1

<#
    .SYNOPSIS
        Edits the documentation for a command by parsing the comment-based help from
        the source file.

    .DESCRIPTION
        Edits the documentation for a command by parsing the comment-based help from
        the source file.

    .PARAMETER FilePath
        Specifies the FileInfo object of the markdown file containing the documentation
        being edited. This parameter is mandatory.

    .EXAMPLE
        $filePath = Get-Item -Path 'C:\Docs\MyCommand.md'
        Edit-CommandDocumentation -FilePath $filePath -SourcePath 'C:\Scripts\MyCommand.ps1'

        Edits the documentation for the command specified in the markdown file "C:\Docs\MyCommand.md"
        using the source file "C:\Scripts\MyCommand.ps1".
#>
function Edit-CommandDocumentation
{
    [CmdletBinding()]
    param
    (
        [Parameter(Mandatory = $true, ValueFromPipeline = $true)]
        [ValidateScript({Test-Path $_ -PathType 'Leaf'})]
        [System.IO.FileInfo]
        $FilePath
    )

    process
    {
        $getMarkdownMetadataScript = @"
Get-MarkdownMetadata -Path $($FilePath.FullName) -ErrorAction 'Stop'
"@

        Write-Debug -Message $getMarkdownMetadataScript

        $getMarkdownMetadataScriptBlock = [ScriptBlock]::Create($getMarkdownMetadataScript)

        $pwshPath = (Get-Process -Id $PID).Path

        <#
            The scriptblock is run in a separate process to avoid conflicts with
            other modules that are loaded in the current process.
        #>
        $markdownMetadata = & $pwshPath -Command $getMarkdownMetadataScriptBlock -ExecutionPolicy 'ByPass' -NoProfile

        if ($markdownMetadata.Type -ne 'Command')
        {
            Write-Information -MessageData "The documentation '$($FilePath.BaseName)' was not a command documentation, skipping." -InformationAction 'Continue'

            continue
        }

        switch ($markdownMetadata.Schema)
        {
            '2.0.0'
            {
                Write-Information -MessageData "Cleaning documentation of '$($FilePath.BaseName)'." -InformationAction 'Continue'

                <#
                    Remove ProgressAction parameter from the documentation. The
                    parameter ProgressAction was introduced in PS 7.4 and is not
                    supported by PlatyPS <v2.0.0.

                    See issue https://github.com/PowerShell/platyPS/issues/595.
                #>
                Remove-ParameterFromMarkdown -FilePath $FilePath -ParameterName 'ProgressAction'

                Remove-EscapedMarkdownCode -FilePath $FilePath
            }

            default
            {
                throw "The markdown file '$($FilePath.FullName)' has an unsupported schema version '$($markdownMetadata.Schema)'."
            }
        }
    }
}
#EndRegion './Public/Edit-CommandDocumentation.ps1' 82
#Region './Public/Invoke-Git.ps1' -1

<#
    .SYNOPSIS
        Invokes a git command.

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

        Throws an error when git ExitCode -ne 0 and -PassThru switch -eq $false (or omitted).

    .PARAMETER WorkingDirectory
        The path to the git working directory.

    .PARAMETER Timeout
        Milliseconds to wait for process to exit.

    .PARAMETER PassThru
        Switch parameter when enabled will return result object of running git command.

    .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 10000 -PassThru

        Invokes the Git executable to return the status while having a 10000 millisecond timeout.
#>
function Invoke-Git
{
    [CmdletBinding()]
    [OutputType([System.Collections.Hashtable])]
    param
    (
        [Parameter(Mandatory = $true)]
        [System.String]
        $WorkingDirectory,

        [Parameter()]
        [System.Int32]
        $TimeOut = 120000,

        [Parameter()]
        [System.Management.Automation.SwitchParameter]
        $PassThru,

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

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

    Write-Verbose -Message ($script:localizedData.InvokingGitMessage -f ($Arguments -join ' '))

    try
    {
        $process = New-Object -TypeName System.Diagnostics.Process
        $process.StartInfo.Arguments = $Arguments
        $process.StartInfo.CreateNoWindow = $true
        $process.StartInfo.FileName = 'git'
        $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)
            {
                $gitResult.ExitCode = $process.ExitCode
                $gitResult.StandardOutput = $process.StandardOutput.ReadToEnd()
                $gitResult.StandardError = $process.StandardError.ReadToEnd()
            }
        }
    }
    catch
    {
        throw $_
    }
    finally
    {
        if ($process)
        {
            $process.Dispose()
        }

        if ($VerbosePreference -ne 'SilentlyContinue' -or `
            $DebugPreference -ne 'SilentlyContinue' -or `
            $PSBoundParameters['Verbose'] -eq $true -or `
            $PSBoundParameters['Debug'] -eq $true)
        {
            $outGitResultSplat = $gitResult.Clone()

            $outGitResultSplat.Add('Command', $Arguments)
            $outGitResultSplat.Add('WorkingDirectory', $WorkingDirectory)

            Out-GitResult @outGitResultSplat
        }

        if ($gitResult.ExitCode -ne 0 -and $PassThru -eq $false)
        {
            $throwMessage = "$($script:localizedData.InvokeGitCommandDebug -f $(Hide-GitToken -Command $Arguments))`n" +`
                            "$($script:localizedData.InvokeGitExitCodeMessage -f $gitResult.ExitCode)`n" +`
                            "$($script:localizedData.InvokeGitStandardOutputMessage -f $gitResult.StandardOutput)`n" +`
                            "$($script:localizedData.InvokeGitStandardErrorMessage -f $gitResult.StandardError)`n"

            throw $throwMessage
        }
    }

    if ($PSBoundParameters['PassThru'] -eq $true)
    {
        return $gitResult
    }
}
#EndRegion './Public/Invoke-Git.ps1' 125
#Region './Public/New-DscResourcePowerShellHelp.ps1' -1

<#
    .SYNOPSIS
        New-DscResourcePowerShellHelp generates PowerShell compatible help files
        for a DSC resource module.

    .DESCRIPTION
        Generates conceptual help based on the DSC resources and their examples in
        a DSC module. This currently only creates English (culture en-US) conceptual
        help. MOF, class-based and composite resources are supported. Class-based resources
        must follow the template pattern of the [Sampler](https://github.com/gaelcolas/Sampler)
        project. See the project [AzureDevOpDsc](https://github.com/dsccommunity/AzureDevOpsDsc)
        for an example of the pattern.

        After the conceptual help has been created, the user can import the module
        and for example run `Get-Help about_UserAccountControl` to get help about
        the DSC resource UserAccountControl.

        It is possible to pass a array of regular expressions that should be used
        to parse the parameter descriptions in the schema MOF. The 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.

        >**NOTE:** This cmdlet does not work on macOS and will throw an error due
        >to the problem discussed in issue https://github.com/PowerShell/PowerShell/issues/5970
        >and issue https://github.com/PowerShell/MMI/issues/33.

        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/MyResourceName/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' 426
#Region './Public/New-DscResourceWikiPage.ps1' -1

<#
    .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,
        class-based and composite 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.

        Generate documentation that can be manually uploaded to the GitHub repository
        Wiki.

        It is possible to use markdown code in the schema MOF parameter descriptions.
        If markdown code is used and conceptual help is also to be generated, configure
        the task [`Generate_Conceptual_Help`](#generate_conceptual_help) to parse the
        markdown code. See the cmdlet `New-DscResourcePowerShellHelp` and the task
        [`Generate_Conceptual_Help`](#generate_conceptual_help) for more information.

    .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.

    .PARAMETER Metadata
        The metadata for the DSC resource markdown files.

    .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.

    .EXAMPLE
        New-DscResourceWikiPage `
            -SourcePath C:\repos\MyResource\source `
            -BuiltModulePath C:\repos\MyResource\output\MyResource\1.0.0 `
            -OutputPath C:\repos\MyResource\output\WikiContent `
            -Metadata @{
                MofResourceMetadata = @{
                    Type = 'MofResource'
                    Category = 'MOF-based resources'
                }
                ClassResourceMetadata = @{
                    Type = 'ClassResource'
                    Category = 'Class-based resources'
                }
                CompositeResourceMetadata = @{
                    Type = 'CompositeResource'
                    Category = 'Composites resources'
                }
            }

        This example shows how to generate wiki documentation for a specific module
        and passing in metadata for the markdown files.
#>
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.Collections.Hashtable]
        $Metadata,

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

    $newDscMofResourceWikiPageParameters = @{
        OutputPath = $OutputPath
        SourcePath = $SourcePath
        Metadata   = $Metadata.MofResourceMetadata
        Force      = $Force
    }

    New-DscMofResourceWikiPage @newDscMofResourceWikiPageParameters

    $newDscClassResourceWikiPageParameters = @{
        OutputPath      = $OutputPath
        SourcePath      = $SourcePath
        BuiltModulePath = $BuiltModulePath
        Metadata        = $Metadata.ClassResourceMetadata
        Force           = $Force
    }

    New-DscClassResourceWikiPage @newDscClassResourceWikiPageParameters

    $newDscCompositeResourceWikiPageParameters = @{
        OutputPath      = $OutputPath
        SourcePath      = $SourcePath
        BuiltModulePath = $BuiltModulePath
        Metadata        = $Metadata.CompositeResourceMetadata
        Force           = $Force
    }

    New-DscCompositeResourceWikiPage @newDscCompositeResourceWikiPageParameters
}
#EndRegion './Public/New-DscResourceWikiPage.ps1' 126
#Region './Public/New-GitHubWikiSidebar.ps1' -1

<#
    .SYNOPSIS
        Creates a GitHub Wiki sidebar based on existing markdown files and their metadata.

    .DESCRIPTION
        This command creates a new GitHub wiki sidebar file with the specified output
        path and sidebar file name. The sidebar is created based on existing markdown
        files and their metadata

    .PARAMETER DocumentationPath
        Specifies the FileInfo object of the markdown file containing the documentation
        being edited. This parameter is mandatory.

    .PARAMETER OutputPath
        Specifies the output path where the sidebar file will be created.

    .PARAMETER SidebarFileName
        Specifies the name of the sidebar file. The default value is '_Sidebar.md'.

    .PARAMETER ReplaceExisting
        Specifies whether to force the creation of the sidebar even if it already exists.
        By default, if the sidebar file already exists, the function will not overwrite it.

    .PARAMETER Force
        Specifies that the sidebar should be created without any confirmation.

    .EXAMPLE
        New-GitHubWikiSidebar -OutputPath 'C:\Wiki' -SidebarFileName 'CustomSidebar.md'

        Creates a new GitHub wiki sidebar file named 'CustomSidebar.md' in the 'C:\Wiki'
        directory.

    .EXAMPLE
        New-GitHubWikiSidebar -DocumentationPath './output/WikiOutput' -Force

        Creates a GitHub Wiki sidebar using default path and filename. The sidebar
        will be created even if it already exists.
#>
function New-GitHubWikiSidebar
{
    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'High')]
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateScript({Test-Path $_ -PathType 'Container'})]
        [System.String]
        $DocumentationPath,

        [Parameter()]
        [ValidateScript({Test-Path $_ -PathType 'Container'})]
        [System.String]
        $OutputPath,

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

        [Parameter()]
        [System.Management.Automation.SwitchParameter]
        $ReplaceExisting,

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

    if ($Force.IsPresent -and -not $Confirm)
    {
        $ConfirmPreference = 'None'
    }

    if (-not $OutputPath)
    {
        $OutputPath = $DocumentationPath
    }

    $sidebarFilePath = Join-Path -Path $OutputPath -ChildPath $SidebarFileName

    <#
        If the sidebar file already exists, don't overwrite it unless the -Force
        parameter is used. This is to prevent overwriting if there are already a
        sidebar that was created or copied to WikiOutput by another task, e.g.
        Generate_Wiki_Content that copies the content of the WikiSource folder
        to WikiOutput.
    #>
    if (-not $ReplaceExisting -and (Test-Path -Path $sidebarFilePath))
    {
        Write-Warning "Sidebar file '$sidebarFilePath' already exists. Leaving it unchanged. Use -ReplaceExisting to overwrite."

        return
    }

    $verboseDescriptionMessage = $script:localizedData.NewGitHubWikiSidebar_ShouldProcessVerboseDescription -f $sidebarFilePath
    $verboseWarningMessage = $script:localizedData.NewGitHubWikiSidebar_ShouldProcessVerboseWarning -f $sidebarFilePath, $DocumentationPath
    $captionMessage = $script:localizedData.NewGitHubWikiSidebar_ShouldProcessCaption

    if (-not $PSCmdlet.ShouldProcess($verboseDescriptionMessage, $verboseWarningMessage, $captionMessage))
    {
        return
    }

    # cSpell: disable-next-line
    $markdownFiles = Get-ChildItem -Path "$DocumentationPath/*.md" -Exclude @('_[Ss]idebar.md', '_[Ff]ooter.md')

    $sidebarCategories = @{}

    foreach ($file in $markdownFiles)
    {
        Write-Debug -Message "Processing file '$($file.FullName)'."

        $getMarkdownMetadataScript = @"
Get-MarkdownMetadata -Path $($file.FullName) -ErrorAction 'Stop'
"@

        Write-Debug -Message $getMarkdownMetadataScript

        $getMarkdownMetadataScriptBlock = [ScriptBlock]::Create($getMarkdownMetadataScript)

        $pwshPath = (Get-Process -Id $PID).Path

        <#
            The scriptblock is run in a separate process to avoid conflicts with
            other modules that are loaded in the current process.
        #>
        $markdownMetadata = & $pwshPath -Command $getMarkdownMetadataScriptBlock -ExecutionPolicy 'ByPass' -NoProfile

        # If the category doesn't exist in the metadata, add it to the default category General.
        if (-not $markdownMetadata -or -not $markdownMetadata.ContainsKey('Category'))
        {
            $markdownMetadata = @{
                Category = 'General'
            }
        }

        Write-Information -MessageData "Found documentation '$($file.BaseName)' of type '$($markdownMetadata.Type)' in category '$($markdownMetadata.Category)'." -InformationAction 'Continue'

        if (-not $sidebarCategories.ContainsKey($markdownMetadata.Category))
        {
            $sidebarCategories[$markdownMetadata.Category] = @()
        }

        $sidebarCategories[$markdownMetadata.Category] += $file.BaseName
    }

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

    # Always put link to Home at the top of the file.
    if ($sidebarCategories.ContainsKey('General'))
    {
        if ($sidebarCategories.General -contains 'Home')
        {
            $null = $output.AppendLine('[Home](Home)')
            $null = $output.AppendLine()
        }
    }

    # Always put category General at the top of the list.
    if ($sidebarCategories.ContainsKey('General'))
    {
        $sortedListItem = $sidebarCategories.General |
            Where-Object -FilterScript {
                $_ -ne 'Home'
            } | Sort-Object

        if ($sortedListItem.Count -gt 0)
        {
            $null = $output.AppendLine('### General')
            $null = $output.AppendLine()

            foreach ($link in $sortedListItem)
            {
                $null = $output.AppendLine('- [' + $link + '](' + $link + ')')
            }

            $null = $output.AppendLine()
        }
    }

    $sortedCategories = $sidebarCategories.Keys |
        Where-Object -FilterScript {
            $_ -ne 'General'
        } | Sort-Object

    foreach ($category in $sortedCategories)
    {
        $null = $output.AppendLine("### $category")
        $null = $output.AppendLine()

        foreach ($link in $sidebarCategories.$category | Sort-Object)
        {
            $null = $output.AppendLine('- [' + $link + '](' + $link + ')')
        }

        $null = $output.AppendLine()
    }

    $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

    $outFileParameters = @{
        InputObject = $outputToWrite
        FilePath = $sidebarFilePath
        Force = $ReplaceExisting
    }

    if ($PSVersionTable.PSVersion -lt '6.0')
    {
        $outFileParameters.Encoding = 'UTF8'
    }
    else
    {
        $outFileParameters.Encoding = [System.Text.Encoding]::UTF8
    }

    $null = Out-File @outFileParameters
}
#EndRegion './Public/New-GitHubWikiSidebar.ps1' 219
#Region './Public/Publish-WikiContent.ps1' -1

<#
    .SYNOPSIS
        Publishes the Wiki Content that is generated by New-DscResourceWikiPage.

    .DESCRIPTION
        Publishes the Wiki content that was generated by the cmdlet `New-DscResourceWikiPage`.

        If there is an existing `_Sidebar.md` present in the `WikiOutput` folder then
        it will be published. If there is no existing `_Sidebar.md` in the `WikiOutput`
        folder a `_Sidebar.md` file will be dynamically generated based on the files
        in the `WikiOutput` folder.

        >**NOTE:** There must already be a Wiki created in the GitHub repository
        >before using this cmdlet, otherwise it will fail since there is no Wiki
        >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'

        Adds the content pages in '.\output\WikiContent' to the Wiki for the
        specified GitHub repository.

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

        Adds the content pages in '.\output\WikiContent' to the Wiki for the
        specified GitHub repository. The wiki repository will be cloned after the
        git configuration setting `--global core.autocrlf` have been set to `true`
        making sure the current wiki files are checkout using CRLF.
#>
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

    $tempFolder = New-TempFolder

    $tempPath = $tempFolder.FullName

    $wikiRepoName = "https://github.com/$OwnerName/$RepositoryName.wiki.git"

    try
    {
        if ($PSBoundParameters.ContainsKey('GlobalCoreAutoCrLf'))
        {
            Write-Verbose -Message $script:localizedData.ConfigGlobalGitMessage

            Invoke-Git -WorkingDirectory $tempPath `
                -Arguments @( 'config', '--global', 'core.autocrlf', $GlobalCoreAutoCrLf )
        }

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

        Invoke-Git -WorkingDirectory $tempPath -Arguments @( 'clone', $wikiRepoName, $tempPath )

        $copyWikiFileParameters = @{
            Path            = $Path
            DestinationPath = $tempPath
            Force           = $true
        }

        Copy-WikiFolder @copyWikiFileParameters

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

        Write-Verbose -Message $script:localizedData.ConfigLocalGitMessage

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

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

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

        Write-Verbose -Message $script:localizedData.AddWikiContentToGitRepoMessage

        Invoke-Git -WorkingDirectory $tempPath -Arguments @( 'add', '*' )

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

        Invoke-Git -WorkingDirectory $tempPath `
            -Arguments @( 'commit', '--message', "`"$($script:localizedData.UpdateWikiCommitMessage -f $ModuleVersion)`"" )

        Write-Verbose -Message $script:localizedData.PushUpdatedRepoMessage

        Invoke-Git -WorkingDirectory $tempPath `
            -Arguments @( 'tag', '--annotate', $ModuleVersion, '--message', $ModuleVersion )

        Invoke-Git -WorkingDirectory $tempPath -Arguments @( 'push', 'origin' )

        Invoke-Git -WorkingDirectory $tempPath -Arguments @( 'push', 'origin', $ModuleVersion )

        Write-Verbose -Message $script:localizedData.PublishWikiContentCompleteMessage
    }
    finally
    {
        Remove-Item -Path $tempPath -Recurse -Force
    }
}
#EndRegion './Public/Publish-WikiContent.ps1' 191
#Region './Public/Remove-MarkdownMetadataBlock.ps1' -1

<#
    .SYNOPSIS
        Removes metadata from a Markdown file.

    .DESCRIPTION
        The Remove-MarkdownMetadataBlock function removes metadata from a Markdown file.
        It searches for a metadata marker ('---') and removes the content between
        the marker and the next occurrence of the marker.

    .PARAMETER FilePath
        Specifies the path to the Markdown file from which the metadata should be removed.

    .PARAMETER Force
        Specifies that the sidebar should be created without any confirmation.

    .EXAMPLE
        Remove-MarkdownMetadataBlock -FilePath 'C:\Path\To\File.md'

        Removes the metadata from the specified Markdown file.
#>
function Remove-MarkdownMetadataBlock
{
    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'High')]
    param
    (
        [Parameter(Mandatory = $true, ValueFromPipeline = $true)]
        [ValidateScript({Test-Path $_ -PathType 'Leaf'})]
        [System.IO.FileInfo]
        $FilePath,

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

    process
    {
        if ($Force.IsPresent -and -not $Confirm)
        {
            $ConfirmPreference = 'None'
        }

        $content = Get-Content -Path $FilePath.FullName -Raw

        $metadataPattern = '^(?s)---.*?---[\r|\n]*'

        if ($content -match $metadataPattern)
        {
            $verboseDescriptionMessage = $script:localizedData.RemoveMarkdownMetadataBlock_ShouldProcessVerboseDescription -f $FilePath.FullName
            $verboseWarningMessage = $script:localizedData.RemoveMarkdownMetadataBlock_ShouldProcessVerboseWarning -f $FilePath.FullName
            $captionMessage = $script:localizedData.RemoveMarkdownMetadataBlock_ShouldProcessCaption

            if ($PSCmdlet.ShouldProcess($verboseDescriptionMessage, $verboseWarningMessage, $captionMessage))
            {
                $content = $content -replace $metadataPattern

                Set-Content -Path $FilePath.FullName -Value $content
            }
        }
    }
}
#EndRegion './Public/Remove-MarkdownMetadataBlock.ps1' 62
#Region './Public/Set-WikiModuleVersion.ps1' -1

<#
    .SYNOPSIS
        Changes all placeholders (#.#.#) in a markdown file to the specified
        module version.

    .DESCRIPTION
        Changes all placeholders (#.#.#) in a markdown file to 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' 42