New Task - Package_Wiki_Content (#144)

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

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
+
+```

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
 }
-

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"

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'
+}

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
 

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 {

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 {

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 {

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 {

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
+        }
+    }
+}