Skip to content

Commit b647f63

Browse files
dan-hughesdan-hughes
authored
Make Generate_Wiki_Content a metatask (#145)
- Task `Generate_Wiki_Content` converted to a metatask. Existing functionality split into smaller tasks. Fixes issue #135
1 parent 589ccbd commit b647f63

11 files changed

+474
-70
lines changed

‎CHANGELOG.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
1313
### Changed
1414

1515
- Skipped failing tests on Linux due to libmi.
16+
- Task `Generate_Wiki_Content` converted to a metatask. Existing
17+
functionality split into smaller tasks. Fixes ([Issue #135](https://github.com/dsccommunity/DscResource.DocGenerator/issues/135))
1618

1719
## [0.12.1] - 2024-01-21
1820

‎source/Private/Task.Copy_Source_Wiki_Folder.ps1

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
<#
2+
.SYNOPSIS
3+
This is the alias to the build task Copy_Source_Wiki_Folder's script file.
4+
5+
.DESCRIPTION
6+
This makes available the alias 'Task.Copy_Source_Wiki_Folder' that is
7+
exported in the module manifest so that the build task can be correctly
8+
imported using for example Invoke-Build.
9+
10+
.NOTES
11+
This is using the pattern lined out in the Invoke-Build repository
12+
https://github.com/nightroman/Invoke-Build/tree/master/Tasks/Import.
13+
#>
14+
15+
Set-Alias -Name 'Task.Copy_Source_Wiki_Folder' -Value "$PSScriptRoot/tasks/Copy_Source_Wiki_Folder.build.ps1"

‎source/Private/Task.Create_Wiki_Output_Folder.ps1

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
<#
2+
.SYNOPSIS
3+
This is the alias to the build task Create_Wiki_Output_Folder's script file.
4+
5+
.DESCRIPTION
6+
This makes available the alias 'Task.Create_Wiki_Output_Folder' that is
7+
exported in the module manifest so that the build task can be correctly
8+
imported using for example Invoke-Build.
9+
10+
.NOTES
11+
This is using the pattern lined out in the Invoke-Build repository
12+
https://github.com/nightroman/Invoke-Build/tree/master/Tasks/Import.
13+
#>
14+
15+
Set-Alias -Name 'Task.Create_Wiki_Output_Folder' -Value "$PSScriptRoot/tasks/Create_Wiki_Output_Folder.build.ps1"

‎source/Private/Task.Generate_Markdown_For_DSC_Resources.ps1

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
<#
2+
.SYNOPSIS
3+
This is the alias to the build task Generate_Markdown_For_DSC_Resources's script file.
4+
5+
.DESCRIPTION
6+
This makes available the alias 'Task.Generate_Markdown_For_DSC_Resources' that is
7+
exported in the module manifest so that the build task can be correctly
8+
imported using for example Invoke-Build.
9+
10+
.NOTES
11+
This is using the pattern lined out in the Invoke-Build repository
12+
https://github.com/nightroman/Invoke-Build/tree/master/Tasks/Import.
13+
#>
14+
15+
Set-Alias -Name 'Task.Generate_Markdown_For_DSC_Resources' -Value "$PSScriptRoot/tasks/Generate_Markdown_For_DSC_Resources.build.ps1"

‎source/tasks/Copy_Source_Wiki_Folder.build.ps1

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
<#
2+
.SYNOPSIS
3+
This is a build task that generates conceptual help.
4+
5+
.PARAMETER ProjectPath
6+
The root path to the project. Defaults to $BuildRoot.
7+
8+
.PARAMETER OutputDirectory
9+
The base directory of all output. Defaults to folder 'output' relative to
10+
the $BuildRoot.
11+
12+
.PARAMETER BuiltModuleSubdirectory
13+
Sub folder where you want to build the Module to (instead of $OutputDirectory/$ModuleName).
14+
This is especially useful when you want to build DSC Resources, but you don't want the
15+
`Get-DscResource` command to find several instances of the same DSC Resources because
16+
of the overlapping $Env:PSmodulePath (`$buildRoot/output` for the built module and `$buildRoot/output/RequiredModules`).
17+
18+
In most cases I would recommend against setting $BuiltModuleSubdirectory.
19+
20+
.PARAMETER VersionedOutputDirectory
21+
Whether the Module is built with its versioned Subdirectory, as you would see it on a System.
22+
For instance, if VersionedOutputDirectory is $true, the built module's ModuleBase would be: `output/MyModuleName/2.0.1/`
23+
24+
.PARAMETER ProjectName
25+
The project name. Defaults to the empty string.
26+
27+
.PARAMETER SourcePath
28+
The path to the source folder name. Defaults to the empty string.
29+
30+
.PARAMETER WikiSourceFolderName
31+
The name of the folder that contains the source markdown files (e.g. 'Home.md')
32+
to publish to the wiki. The name should be relative to the SourcePath.
33+
Defaults to 'WikiSource'.
34+
35+
.PARAMETER BuildInfo
36+
The build info object from ModuleBuilder. Defaults to an empty hashtable.
37+
38+
.NOTES
39+
This is a build task that is primarily meant to be run by Invoke-Build but
40+
wrapped by the Sampler project's build.ps1 (https://github.com/gaelcolas/Sampler).
41+
42+
The function Set-WikiModuleVersion needed to be made a public function
43+
for the build task to find it. Set-WikiModuleVersion function does not
44+
need to be public so if there is a way found in the future that makes it
45+
possible to have it as a private function then this code should refactored
46+
to make that happen.
47+
#>
48+
param
49+
(
50+
[Parameter()]
51+
[System.String]
52+
$ProjectPath = (property ProjectPath $BuildRoot),
53+
54+
[Parameter()]
55+
[System.String]
56+
$OutputDirectory = (property OutputDirectory (Join-Path $BuildRoot 'output')),
57+
58+
[Parameter()]
59+
[System.String]
60+
$BuiltModuleSubdirectory = (property BuiltModuleSubdirectory ''),
61+
62+
[Parameter()]
63+
[System.Management.Automation.SwitchParameter]
64+
$VersionedOutputDirectory = (property VersionedOutputDirectory $true),
65+
66+
[Parameter()]
67+
[System.String]
68+
$ProjectName = (property ProjectName ''),
69+
70+
[Parameter()]
71+
[System.String]
72+
$SourcePath = (property SourcePath ''),
73+
74+
[Parameter()]
75+
[System.String]
76+
$WikiSourceFolderName = (property WikiSourceFolderName 'WikiSource'),
77+
78+
[Parameter()]
79+
[System.String]
80+
$WikiOutputPath = (property WikiOutputPath ''),
81+
82+
[Parameter()]
83+
[System.Collections.Hashtable]
84+
$BuildInfo = (property BuildInfo @{ })
85+
)
86+
87+
# Synopsis: Generate wiki documentation for the DSC resources.
88+
Task Copy_Source_Wiki_Folder {
89+
# Get the values for task variables, see https://github.com/gaelcolas/Sampler#task-variables.
90+
. Set-SamplerTaskVariable
91+
92+
$wikiSourcePath = Join-Path -Path $SourcePath -ChildPath $WikiSourceFolderName
93+
$wikiOutputPath = Join-Path -Path $OutputDirectory -ChildPath 'WikiContent'
94+
95+
$wikiSourceExist = Test-Path -Path $wikiSourcePath
96+
97+
if ($wikiSourceExist)
98+
{
99+
"`tWiki Source Path = $wikiSourcePath"
100+
}
101+
102+
if ($wikiSourceExist)
103+
{
104+
Write-Build -Color 'Magenta' -Text 'Copying Wiki content from the Wiki source folder.'
105+
106+
Copy-Item -Path (Join-Path $wikiSourcePath -ChildPath '*') -Destination $wikiOutputPath -Recurse -Force
107+
108+
$homeMarkdownFilePath = Join-Path -Path $wikiOutputPath -ChildPath 'Home.md'
109+
110+
if (Test-Path -Path $homeMarkdownFilePath)
111+
{
112+
Write-Build -Color 'Magenta' -Text 'Updating module version in Home.md if there are any placeholders found.'
113+
114+
Set-WikiModuleVersion -Path $homeMarkdownFilePath -ModuleVersion $moduleVersion
115+
}
116+
}
117+
}

‎source/tasks/Create_Wiki_Output_Folder.build.ps1

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
<#
2+
.SYNOPSIS
3+
This is a build task that generates conceptual help.
4+
5+
.PARAMETER ProjectPath
6+
The root path to the project. Defaults to $BuildRoot.
7+
8+
.PARAMETER OutputDirectory
9+
The base directory of all output. Defaults to folder 'output' relative to
10+
the $BuildRoot.
11+
12+
.PARAMETER BuiltModuleSubdirectory
13+
Sub folder where you want to build the Module to (instead of $OutputDirectory/$ModuleName).
14+
This is especially useful when you want to build DSC Resources, but you don't want the
15+
`Get-DscResource` command to find several instances of the same DSC Resources because
16+
of the overlapping $Env:PSmodulePath (`$buildRoot/output` for the built module and `$buildRoot/output/RequiredModules`).
17+
18+
In most cases I would recommend against setting $BuiltModuleSubdirectory.
19+
20+
.PARAMETER VersionedOutputDirectory
21+
Whether the Module is built with its versioned Subdirectory, as you would see it on a System.
22+
For instance, if VersionedOutputDirectory is $true, the built module's ModuleBase would be: `output/MyModuleName/2.0.1/`
23+
24+
.PARAMETER ProjectName
25+
The project name. Defaults to the empty string.
26+
27+
.PARAMETER SourcePath
28+
The path to the source folder name. Defaults to the empty string.
29+
30+
.PARAMETER WikiSourceFolderName
31+
The name of the folder that contains the source markdown files (e.g. 'Home.md')
32+
to publish to the wiki. The name should be relative to the SourcePath.
33+
Defaults to 'WikiSource'.
34+
35+
.PARAMETER BuildInfo
36+
The build info object from ModuleBuilder. Defaults to an empty hashtable.
37+
38+
.NOTES
39+
This is a build task that is primarily meant to be run by Invoke-Build but
40+
wrapped by the Sampler project's build.ps1 (https://github.com/gaelcolas/Sampler).
41+
42+
The function Set-WikiModuleVersion needed to be made a public function
43+
for the build task to find it. Set-WikiModuleVersion function does not
44+
need to be public so if there is a way found in the future that makes it
45+
possible to have it as a private function then this code should refactored
46+
to make that happen.
47+
#>
48+
param
49+
(
50+
[Parameter()]
51+
[System.String]
52+
$ProjectPath = (property ProjectPath $BuildRoot),
53+
54+
[Parameter()]
55+
[System.String]
56+
$OutputDirectory = (property OutputDirectory (Join-Path $BuildRoot 'output')),
57+
58+
[Parameter()]
59+
[System.String]
60+
$BuiltModuleSubdirectory = (property BuiltModuleSubdirectory ''),
61+
62+
[Parameter()]
63+
[System.Management.Automation.SwitchParameter]
64+
$VersionedOutputDirectory = (property VersionedOutputDirectory $true),
65+
66+
[Parameter()]
67+
[System.String]
68+
$ProjectName = (property ProjectName ''),
69+
70+
[Parameter()]
71+
[System.String]
72+
$SourcePath = (property SourcePath ''),
73+
74+
[Parameter()]
75+
[System.String]
76+
$WikiSourceFolderName = (property WikiSourceFolderName 'WikiSource'),
77+
78+
[Parameter()]
79+
[System.Collections.Hashtable]
80+
$BuildInfo = (property BuildInfo @{ })
81+
)
82+
83+
# Synopsis: Create documentation output diretory for the DSC resources.
84+
Task Create_Wiki_Output_Folder {
85+
# Get the values for task variables, see https://github.com/gaelcolas/Sampler#task-variables.
86+
. Set-SamplerTaskVariable
87+
88+
$wikiOutputPath = Join-Path -Path $OutputDirectory -ChildPath 'WikiContent'
89+
90+
if ((Test-Path -Path $wikiOutputPath) -eq $false)
91+
{
92+
$null = New-Item -Path $wikiOutputPath -ItemType Directory
93+
}
94+
95+
"`tWiki Output Path = $wikiOutputPath"
96+
}

‎source/tasks/Generate_Markdown_For_DSC_Resources.build.ps1

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
<#
2+
.SYNOPSIS
3+
This is a build task that generates conceptual help.
4+
5+
.PARAMETER ProjectPath
6+
The root path to the project. Defaults to $BuildRoot.
7+
8+
.PARAMETER OutputDirectory
9+
The base directory of all output. Defaults to folder 'output' relative to
10+
the $BuildRoot.
11+
12+
.PARAMETER BuiltModuleSubdirectory
13+
Sub folder where you want to build the Module to (instead of $OutputDirectory/$ModuleName).
14+
This is especially useful when you want to build DSC Resources, but you don't want the
15+
`Get-DscResource` command to find several instances of the same DSC Resources because
16+
of the overlapping $Env:PSmodulePath (`$buildRoot/output` for the built module and `$buildRoot/output/RequiredModules`).
17+
18+
In most cases I would recommend against setting $BuiltModuleSubdirectory.
19+
20+
.PARAMETER VersionedOutputDirectory
21+
Whether the Module is built with its versioned Subdirectory, as you would see it on a System.
22+
For instance, if VersionedOutputDirectory is $true, the built module's ModuleBase would be: `output/MyModuleName/2.0.1/`
23+
24+
.PARAMETER ProjectName
25+
The project name. Defaults to the empty string.
26+
27+
.PARAMETER SourcePath
28+
The path to the source folder name. Defaults to the empty string.
29+
30+
.PARAMETER WikiSourceFolderName
31+
The name of the folder that contains the source markdown files (e.g. 'Home.md')
32+
to publish to the wiki. The name should be relative to the SourcePath.
33+
Defaults to 'WikiSource'.
34+
35+
.PARAMETER BuildInfo
36+
The build info object from ModuleBuilder. Defaults to an empty hashtable.
37+
38+
.NOTES
39+
This is a build task that is primarily meant to be run by Invoke-Build but
40+
wrapped by the Sampler project's build.ps1 (https://github.com/gaelcolas/Sampler).
41+
42+
The function Set-WikiModuleVersion needed to be made a public function
43+
for the build task to find it. Set-WikiModuleVersion function does not
44+
need to be public so if there is a way found in the future that makes it
45+
possible to have it as a private function then this code should refactored
46+
to make that happen.
47+
#>
48+
param
49+
(
50+
[Parameter()]
51+
[System.String]
52+
$ProjectPath = (property ProjectPath $BuildRoot),
53+
54+
[Parameter()]
55+
[System.String]
56+
$OutputDirectory = (property OutputDirectory (Join-Path $BuildRoot 'output')),
57+
58+
[Parameter()]
59+
[System.String]
60+
$BuiltModuleSubdirectory = (property BuiltModuleSubdirectory ''),
61+
62+
[Parameter()]
63+
[System.Management.Automation.SwitchParameter]
64+
$VersionedOutputDirectory = (property VersionedOutputDirectory $true),
65+
66+
[Parameter()]
67+
[System.String]
68+
$ProjectName = (property ProjectName ''),
69+
70+
[Parameter()]
71+
[System.String]
72+
$SourcePath = (property SourcePath ''),
73+
74+
[Parameter()]
75+
[System.String]
76+
$WikiSourceFolderName = (property WikiSourceFolderName 'WikiSource'),
77+
78+
[Parameter()]
79+
[System.Collections.Hashtable]
80+
$BuildInfo = (property BuildInfo @{ })
81+
)
82+
83+
# Synopsis: Generate wiki documentation for the DSC resources.
84+
Task Generate_Markdown_For_DSC_Resources {
85+
# Get the values for task variables, see https://github.com/gaelcolas/Sampler#task-variables.
86+
. Set-SamplerTaskVariable
87+
88+
$wikiOutputPath = Join-Path -Path $OutputDirectory -ChildPath 'WikiContent'
89+
90+
Write-Build -Color 'Magenta' -Text 'Generating Wiki content for all DSC resources based on source and built module.'
91+
92+
$dscResourceMarkdownMetadata = $BuildInfo.'DscResource.DocGenerator'.Generate_Markdown_For_DSC_Resources
93+
94+
New-DscResourceWikiPage -SourcePath $SourcePath -BuiltModulePath $builtModuleBase -OutputPath $wikiOutputPath -Metadata $dscResourceMarkdownMetadata -Force
95+
}

0 commit comments

Comments
 (0)