diff --git a/CHANGELOG.md b/CHANGELOG.md index 2cfb6d4..83e029f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Added + +- Task `Package_Wiki_Content` - This task will compress generated documentation + into a .zip archive. + +### Changed + +- Skipped failing tests on Linux due to libmi. + ## [0.12.1] - 2024-01-21 ### Fixed diff --git a/README.md b/README.md index 1dbc5a4..4e7f923 100644 --- a/README.md +++ b/README.md @@ -420,3 +420,32 @@ DscResource.DocGenerator: Publish_GitHub_Wiki_Content: Debug: true ``` + +### `Package_Wiki_Content` + +This build task runs the command `Compress-Archive`. + +Below is an example how the build task can be used when a repository is +based on the [Sampler](https://github.com/gaelcolas/Sampler) project. + +>**NOTE:** This task is meant to be run after the task `Generate_Wiki_Content` +>that is normally run in the docs phase. But this task can be used to upload +>any content to a Wiki. + +```yaml +BuildWorkflow: + '.': + - build + + build: + - Clean + - Build_Module_ModuleBuilder + - Build_NestedModules_ModuleBuilder + - Create_changelog_release_output + + docs: + - Generate_Conceptual_Help + - Generate_Wiki_Content + - Package_Wiki_Content + +``` diff --git a/source/DscResource.DocGenerator.psd1 b/source/DscResource.DocGenerator.psd1 index 5ed2882..0bb681f 100644 --- a/source/DscResource.DocGenerator.psd1 +++ b/source/DscResource.DocGenerator.psd1 @@ -55,6 +55,7 @@ AliasesToExport = @( 'Task.Generate_Conceptual_Help', 'Task.Generate_Wiki_Content', + 'Task.Package_Wiki_Content', 'Task.Publish_GitHub_Wiki_Content' ) @@ -85,4 +86,3 @@ } # End of PSData hashtable } # End of PrivateData hashtable } - diff --git a/source/Private/Task.Package_Wiki_Content.ps1 b/source/Private/Task.Package_Wiki_Content.ps1 new file mode 100644 index 0000000..4759576 --- /dev/null +++ b/source/Private/Task.Package_Wiki_Content.ps1 @@ -0,0 +1,15 @@ +<# + .SYNOPSIS + This is the alias to the build task Package_Wiki_Content's script file. + + .DESCRIPTION + This makes available the alias 'Task.Package_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.Package_Wiki_Content' -Value "$PSScriptRoot/tasks/Package_Wiki_Content.build.ps1" diff --git a/source/tasks/Package_Wiki_Content.build.ps1 b/source/tasks/Package_Wiki_Content.build.ps1 new file mode 100644 index 0000000..ef0e15c --- /dev/null +++ b/source/tasks/Package_Wiki_Content.build.ps1 @@ -0,0 +1,60 @@ +<# + .SYNOPSIS + This is a build task that generates conceptual help. + + .PARAMETER OutputDirectory + The base directory of all output. Defaults to folder 'output' relative to + the $BuildRoot. + + .PARAMETER ProjectName + The project name. Defaults to the Project Name. + + .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] + $OutputDirectory = (property OutputDirectory (Join-Path $BuildRoot 'output')), + + [Parameter()] + [System.String] + $ProjectName = (property ProjectName $(Get-SamplerProjectName -BuildRoot $BuildRoot)), + + [Parameter()] + [System.Collections.Hashtable] + $BuildInfo = (property BuildInfo @{ }) +) + +# Synopsis: Package wiki documentation for the DSC resources. +task Package_Wiki_Content { + # Get the values for task variables, see https://github.com/gaelcolas/Sampler#task-variables. + . Set-SamplerTaskVariable + + "`tProject Name = {0}" -f $ProjectName + "`tOutput Directory = {0}" -f $OutputDirectory + + $wikiOutputPath = Join-Path -Path $OutputDirectory -ChildPath 'WikiContent' + $wikiArchiveSourcePath = Join-Path -Path $wikiOutputPath -ChildPath '*' + $wikiPackagePath = Join-Path -Path $OutputDirectory -ChildPath 'WikiContent.zip' + + "`tWiki Output Path = $wikiOutputPath" + "`tWiki Archive Source Path = $wikiArchiveSourcePath" + "`tWiki Package Path = $wikiPackagePath" + + if (-not (Test-Path -Path $wikiOutputPath)) + { + throw 'The Wiki Output Path does not exist. Please run the task Generate_Wiki_Content prior to running this task.' + } + + Write-Build Magenta 'Packaging Wiki content.' + + # Overwrites any existing archive. + Compress-Archive -Path $wikiArchiveSourcePath -DestinationPath $wikiPackagePath -CompressionLevel 'Optimal' -Force -ErrorAction 'Stop' +} diff --git a/tests/unit/private/Get-CompositeResourceParameterState.Tests.ps1 b/tests/unit/private/Get-CompositeResourceParameterState.Tests.ps1 index 3f40832..525e710 100644 --- a/tests/unit/private/Get-CompositeResourceParameterState.Tests.ps1 +++ b/tests/unit/private/Get-CompositeResourceParameterState.Tests.ps1 @@ -16,10 +16,14 @@ $script:moduleName = Get-Module -Name $script:projectName -ListAvailable | Selec Remove-Module -Name $script:moduleName -Force -ErrorAction 'SilentlyContinue' Import-Module $script:moduleName -Force -ErrorAction 'Stop' + +if ($IsLinux) { + return +} #endregion HEADER InModuleScope $script:moduleName { - Describe 'Get-CompositeResourceParameterState' { + Describe 'Get-CompositeResourceParameterState'{ BeforeAll { $script:tokens, $script:parseErrors = $null diff --git a/tests/unit/private/Get-CompositeResourceParameterValidateSet.Tests.ps1 b/tests/unit/private/Get-CompositeResourceParameterValidateSet.Tests.ps1 index 4efc7af..230b123 100644 --- a/tests/unit/private/Get-CompositeResourceParameterValidateSet.Tests.ps1 +++ b/tests/unit/private/Get-CompositeResourceParameterValidateSet.Tests.ps1 @@ -16,6 +16,10 @@ $script:moduleName = Get-Module -Name $script:projectName -ListAvailable | Selec Remove-Module -Name $script:moduleName -Force -ErrorAction 'SilentlyContinue' Import-Module $script:moduleName -Force -ErrorAction 'Stop' + +if ($IsLinux) { + return +} #endregion HEADER InModuleScope $script:moduleName { diff --git a/tests/unit/private/Get-CompositeSchemaObject.Tests.ps1 b/tests/unit/private/Get-CompositeSchemaObject.Tests.ps1 index 8ed71e3..b59a788 100644 --- a/tests/unit/private/Get-CompositeSchemaObject.Tests.ps1 +++ b/tests/unit/private/Get-CompositeSchemaObject.Tests.ps1 @@ -16,6 +16,10 @@ $script:moduleName = Get-Module -Name $script:projectName -ListAvailable | Selec Remove-Module -Name $script:moduleName -Force -ErrorAction 'SilentlyContinue' Import-Module $script:moduleName -Force -ErrorAction 'Stop' + +if ($IsLinux) { + return +} #endregion HEADER InModuleScope $script:moduleName { diff --git a/tests/unit/private/Get-ConfigurationAst.Tests.ps1 b/tests/unit/private/Get-ConfigurationAst.Tests.ps1 index 1492f58..ee38d18 100644 --- a/tests/unit/private/Get-ConfigurationAst.Tests.ps1 +++ b/tests/unit/private/Get-ConfigurationAst.Tests.ps1 @@ -16,6 +16,10 @@ $script:moduleName = Get-Module -Name $script:projectName -ListAvailable | Selec Remove-Module -Name $script:moduleName -Force -ErrorAction 'SilentlyContinue' Import-Module $script:moduleName -Force -ErrorAction 'Stop' + +if ($IsLinux) { + return +} #endregion HEADER InModuleScope $script:moduleName { diff --git a/tests/unit/private/Get-MofSchemaObject.Tests.ps1 b/tests/unit/private/Get-MofSchemaObject.Tests.ps1 index 6a3d8cb..abc11d3 100644 --- a/tests/unit/private/Get-MofSchemaObject.Tests.ps1 +++ b/tests/unit/private/Get-MofSchemaObject.Tests.ps1 @@ -16,6 +16,10 @@ $script:moduleName = Get-Module -Name $script:projectName -ListAvailable | Selec Remove-Module -Name $script:moduleName -Force -ErrorAction 'SilentlyContinue' Import-Module $script:moduleName -Force -ErrorAction 'Stop' + +if ($IsLinux) { + return +} #endregion HEADER InModuleScope $script:moduleName { diff --git a/tests/unit/tasks/Package_Wiki_Content.build.Tests.ps1 b/tests/unit/tasks/Package_Wiki_Content.build.Tests.ps1 new file mode 100644 index 0000000..8895c3f --- /dev/null +++ b/tests/unit/tasks/Package_Wiki_Content.build.Tests.ps1 @@ -0,0 +1,82 @@ +#region HEADER +$script:projectPath = "$PSScriptRoot\..\..\.." | Convert-Path +$script:projectName = (Get-ChildItem -Path "$script:projectPath\*\*.psd1" | Where-Object -FilterScript { + ($_.Directory.Name -match 'source|src' -or $_.Directory.Name -eq $_.BaseName) -and + $(try + { + Test-ModuleManifest -Path $_.FullName -ErrorAction Stop + } + catch + { + $false + }) + }).BaseName + +$script:moduleName = Get-Module -Name $script:projectName -ListAvailable | Select-Object -First 1 +Remove-Module -Name $script:moduleName -Force -ErrorAction 'SilentlyContinue' + +Import-Module $script:moduleName -Force -ErrorAction 'Stop' +#endregion HEADER + +Describe 'Package_Wiki_Content' { + BeforeAll { + Mock -CommandName Compress-Archive + } + + It 'Should export the build script alias' { + $buildTaskName = 'Package_Wiki_Content' + $buildScriptAliasName = 'Task.{0}' -f $buildTaskName + + $script:buildScript = Get-Command -Name $buildScriptAliasName -Module $script:projectName + + $script:buildScript.Name | Should -Be $buildScriptAliasName + $script:buildScript.ReferencedCommand | Should -Be ('{0}.build.ps1' -f $buildTaskName) + } + + It 'Should reference an existing build script' { + Test-Path -Path $script:buildScript.Definition | Should -BeTrue + } + + Context 'When path is valid' { + BeforeAll { + Mock -CommandName Test-Path -MockWith { + return $true + } + } + + It 'Should run the build task without throwing' { + { + $taskParameters = @{ + ProjectName = 'DscResource.DocGenerator' + OutputDirectory = $TestDrive.FullName + } + + Invoke-Build -Task $buildTaskName -File $script:buildScript.Definition @taskParameters + } | Should -Not -Throw + + Assert-MockCalled -CommandName Test-Path -Exactly -Times 2 -Scope It + Assert-MockCalled -CommandName Compress-Archive -Exactly -Times 1 -Scope It + } + } + + Context 'When path is invalid' { + BeforeAll { + Mock -CommandName Test-Path -MockWith { + return $false + } + } + + It 'Should run the build task and throw' { + { + $taskParameters = @{ + ProjectName = 'DscResource.DocGenerator' + OutputDirectory = $TestDrive.FullName + } + + Invoke-Build -Task $buildTaskName -File $script:buildScript.Definition @taskParameters + } | Should -Throw + + Assert-MockCalled -CommandName Test-Path -Exactly -Times 2 -Scope It + } + } +}