tasks/Generate_Conceptual_Help.build.ps1

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
<#
    .SYNOPSIS
        This is a build task that generates conceptual help.
 
    .PARAMETER ProjectPath
        The root path to the project. Defaults to $BuildRoot.
 
    .PARAMETER OutputDirectory
        The base directory of all output. Defaults to folder 'output' relative to
        the $BuildRoot.
 
    .PARAMETER ProjectName
        The project name. Defaults to the BaseName of the module manifest it finds
        in either the folder 'source', 'src, or a folder with the same name as
        the module.
 
    .PARAMETER SourcePath
        The path to the source folder name. Defaults to the same path where the
        module manifest is found.
 
    .PARAMETER ModuleVersion
        The module version of the build module, e.g. '99.1.1-preview0001'. Defaults
        to using the value from parent scope, if that is not available it defaults
        to the property NuGetVersionV2 returned by GitVersion. If GitVersion is not
        present, the parameter defaults to version '0.0.1'.
 
    .PARAMETER BuildInfo
        The build info object from ModuleBuilder. Defaults to an empty hashtable.
 
    .NOTES
        This is a build task that is primarily meant to be run by Invoke-Build but
        wrapped by the Sampler project's build.ps1 (https://github.com/gaelcolas/Sampler).
#>

param
(
    [Parameter()]
    [System.String]
    $ProjectPath = (property ProjectPath $BuildRoot),

    [Parameter()]
    [System.String]
    $OutputDirectory = (property OutputDirectory (Join-Path $BuildRoot 'output')),

    [Parameter()]
    [System.String]
    $ProjectName = (property ProjectName $(
            # Find the module manifest to deduce the Project Name
            (Get-ChildItem $BuildRoot\*\*.psd1 -Exclude @('build.psd1', 'analyzersettings.psd1') | Where-Object -FilterScript {
                    ($_.Directory.Name -match 'source|src' -or $_.Directory.Name -eq $_.BaseName) -and
                    $(
                        try
                        {
                            Test-ModuleManifest $_.FullName -ErrorAction Stop
                        }
                        catch
                        {
                            Write-Warning -Message $_
                            $false
                        }
                    )
                }).BaseName
        )
    ),

    [Parameter()]
    [System.String]
    $SourcePath = (property SourcePath $(
            (Get-ChildItem $BuildRoot\*\*.psd1 -Exclude @('build.psd1', 'analyzersettings.psd1') | Where-Object -FilterScript {
                    ($_.Directory.Name -match 'source|src' -or $_.Directory.Name -eq $_.BaseName) -and
                    $(
                        try
                        {
                            Test-ModuleManifest $_.FullName -ErrorAction Stop
                        }
                        catch
                        {
                            Write-Warning -Message $_
                            $false
                        }
                    )
                }).Directory.FullName
        )
    ),

    [Parameter()]
    [System.String]
    $ModuleVersion = (property ModuleVersion $(
            try
            {
                (gitversion | ConvertFrom-Json -ErrorAction Stop).NuGetVersionV2
            }
            catch
            {
                Write-Verbose -Message "Error attempting to use GitVersion $($_)."
                ''
            }
        )),

    [Parameter()]
    $BuildInfo = (property BuildInfo @{ })
)

# Synopsis: This task generates conceptual help for DSC resources.
task Generate_Conceptual_Help {
    if (-not (Split-Path -IsAbsolute $OutputDirectory))
    {
        $OutputDirectory = Join-Path -Path $ProjectPath -ChildPath $OutputDirectory
    }

    $getModuleVersionParameters = @{
        OutputDirectory = $OutputDirectory
        ProjectName     = $ProjectName
        ModuleVersion   = $ModuleVersion
    }

    $ModuleVersion = Get-ModuleVersion @getModuleVersionParameters
    $ModuleVersionFolder, $PreReleaseString = $ModuleVersion -split '\-', 2

    $builtModulePath = Join-Path -Path (Join-Path -Path $OutputDirectory -ChildPath $ProjectName) -ChildPath $ModuleVersionFolder

    "`tProject Path = $ProjectPath"
    "`tProject Name = $ProjectName"
    "`tModule Version = $ModuleVersion"
    "`tModule Version Folder = $ModuleVersionFolder"
    "`tPrerelease String = $PreReleaseString"
    "`tSource Path = $SourcePath"
    "`tBuilt Module Path = $builtModulePath"

    Write-Build Magenta "Generating conceptual help for all DSC resources based on source."

    New-DscResourcePowerShellHelp -ModulePath $SourcePath -DestinationModulePath $builtModulePath
}