tasks/Publish_GitHub_Wiki_Content.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
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
<#
    .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 WikiContentFolderName
        The name of the folder that contain the content to publish to the wiki.
        The name should be relative to the OutputDirectory. Defaults to 'WikiContent'.
 
    .PARAMETER GitHubToken
        The token to use to push a commit and tag to the wiki repository. Defaults
        to an empty string.
 
    .PARAMETER GitHubConfigUserEmail
        The e-mail address to use for the commit. Defaults to an empty string.
 
    .PARAMETER GitHubConfigUserName
        The username to use for the commit. Defaults to an empty string.
 
    .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 -Path $_.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 -Path $_.FullName -ErrorAction 'Stop'
                        }
                        catch
                        {
                            Write-Warning -Message $_
                            $false
                        }
                    )
                }).Directory.FullName
        )
    ),

    [Parameter()]
    [System.String]
    $WikiContentFolderName = (property WikiContentFolderName 'WikiContent'),

    [Parameter()]
    [System.String]
    $GitHubToken = (property GitHubToken ''),

    [Parameter()]
    [System.String]
    $GitHubConfigUserEmail = (property GitHubConfigUserEmail ''),

    [Parameter()]
    [System.String]
    $GitHubConfigUserName = (property GitHubConfigUserName ''),

    [Parameter()]
    [System.Collections.Hashtable]
    $BuildInfo = (property BuildInfo @{ })
)

# Synopsis: This task publishes documentation to a GitHub Wiki repository.
task Publish_GitHub_Wiki_Content -if ($GitHubToken) {
    if (-not (Split-Path -IsAbsolute $OutputDirectory))
    {
        $OutputDirectory = Join-Path -Path $ProjectPath -ChildPath $OutputDirectory
    }

    $getBuiltModuleVersionParameters = @{
        OutputDirectory = $OutputDirectory
        ProjectName     = $ProjectName
    }

    $moduleVersion = Get-BuiltModuleVersion @getBuiltModuleVersionParameters

    # If variables are not set then update variables from the property values in the build.yaml.
    foreach ($gitHubConfigKey in @('GitHubConfigUserName', 'GitHubConfigUserEmail'))
    {
        if (-not (Get-Variable -Name $gitHubConfigKey -ValueOnly -ErrorAction 'SilentlyContinue'))
        {
            # Variable is not set in context, use $BuildInfo.GitHubConfig.<varName>
            $gitHubConfigKeyValue = $BuildInfo.GitHubConfig.($gitHubConfigKey)

            Set-Variable -Name $gitHubConfigKey -Value $gitHubConfigKeyValue
            Write-Build DarkGray "Set $gitHubConfigKey to $gitHubConfigKeyValue"
        }
    }

    $remoteURL = git remote get-url origin

    # Parse the URL for owner name and repository name.
    if ($remoteURL -match '(http[s]?:\/\/)([^:\/\s]+)\/(\w+)\/(.+)')
    {
        $ownerName = $Matches[3]
        $repositoryName = $Matches[4]
    }
    else
    {
        throw 'Could not parse owner and repository from the git remote origin URL.'
    }

    $wikiOutputPath = Join-Path -Path $OutputDirectory -ChildPath $WikiContentFolderName

    "`tProject Path = $ProjectPath"
    "`tProject Name = $ProjectName"
    "`tModule Version = $moduleVersion"
    "`tSource Path = $SourcePath"
    "`tRepository Owner Name = $ownerName"
    "`tRepository Name = $repositoryName"
    "`tOutput Directory = $OutputDirectory"
    "`tWiki Output Path = $wikiOutputPath"

    $publishWikiContentParameters = @{
        Path = $wikiOutputPath
        OwnerName = $ownerName
        RepositoryName = $repositoryName
        ModuleName = $ProjectName
        ModuleVersion = $moduleVersion
        GitHubAccessToken = $GitHubToken
        GitUserEmail = $GitHubConfigUserEmail
        GitUserName = $GitHubConfigUserName
    }

    Write-Build Magenta "Publishing Wiki content."

    Publish-WikiContent @publishWikiContentParameters
}