tasks/Generate_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
<#
    .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 WikiSourceFolderName
        The name of the folder that contains the source markdown files (e.g. 'Home.md')
        to publish to the wiki. The name should be relative to the SourcePath.
        Defaults to 'WikiSource'.
 
    .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).
 
        The function Set-WikiModuleVersion needed to be made a public function
        for the build task to find it. Set-WikiModuleVersion function does not
        need to be public so if there is a way found in the future that makes it
        possible to have it as a private function then this code should refactored
        to make that happen.
#>

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]
    $WikiSourceFolderName = (property WikiSourceFolderName 'WikiSource'),

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

# Synopsis: This task generates wiki documentation for the DSC resources.
task Generate_Wiki_Content {
    if (-not (Split-Path -IsAbsolute $OutputDirectory))
    {
        $OutputDirectory = Join-Path -Path $ProjectPath -ChildPath $OutputDirectory
    }

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

    $moduleVersion = Get-BuiltModuleVersion @getBuiltModuleVersionParameters

    $wikiOutputPath = Join-Path -Path $OutputDirectory -ChildPath 'WikiContent'

    if ((Test-Path -Path $wikiOutputPath) -eq $false)
    {
        $null = New-Item -Path $wikiOutputPath -ItemType Directory
    }

    "`tProject Path = $ProjectPath"
    "`tProject Name = $ProjectName"
    "`tModule Version = $moduleVersion"
    "`tSource Path = $SourcePath"
    "`tWiki Output Path = $wikiOutputPath"

    $wikiSourcePath = Join-Path -Path $SourcePath -ChildPath $WikiSourceFolderName

    $wikiSourceExist = Test-Path -Path $wikiSourcePath

    if ($wikiSourceExist)
    {
        "`tWiki Source Path = $wikiSourcePath"
    }

    Write-Build Magenta "Generating Wiki content for all DSC resources based on source."

    New-DscResourceWikiPage -ModulePath $SourcePath -OutputPath $wikiOutputPath

    if ($wikiSourceExist)
    {
        Write-Build Magenta "Copying Wiki content from the Wiki source folder."

        Copy-Item -Path (Join-Path $wikiSourcePath -ChildPath '*') -Destination $wikiOutputPath -Force

        $homeMarkdownFilePath = Join-Path -Path $wikiOutputPath -ChildPath 'Home.md'

        if (Test-Path -Path $homeMarkdownFilePath)
        {
            Write-Build Magenta "Updating module version in Home.md if there are any placeholders found."

            Set-WikiModuleVersion -Path $homeMarkdownFilePath -ModuleVersion $moduleVersion
        }
    }
}