Merge pull request #334 from X-Guardian/PowerShellHelp-OutputPath-Fix

New-DscResourcePowerShellHelp: Restore OutputPath parameter

Author: PlagueHO

CHANGELOG.md

@@ -54,7 +54,7 @@
       file that do not exist in the en-US resource file.
 - Added `Publish-WikiContent` helper function to publish auto-generated Wiki files
   to the relevant DSC resource GitHub Wiki ([issue #142](https://github.com/PowerShell/DscResource.Tests/issues/142)).
-- Update New-DscResourcePowerShellHelp to output the PowerShell help files to
+- Update New-DscResourcePowerShellHelp to optionally output the PowerShell help files to
   the resource specific path and fix the example processing.
 - Added processing to `Test-PublishMetaData` for the InvalidGUID error from Test-ScriptFileInfo
   ([issue #330](https://github.com/PowerShell/DscResource.Tests/issues/330)).

DscResource.DocumentationHelper/PowerShellHelp.psm1

@@ -25,27 +25,28 @@ $script:localizedData = Get-LocalizedData -ModuleName $moduleName -ModuleRoot $P
 
 <#
 .SYNOPSIS
-
 New-DscResourcePowerShellHelp generates PowerShell compatible help files for a DSC
 resource module
 
 .DESCRIPTION
-
 The New-DscResourcePowerShellHelp cmdlet will review all of the MOF based resources
-in a specified module directory and will inject PowerShell help files for each resource
-in to the resource's subdirectory. These help files include details on the property types for
-each resource, as well as a text description and examples where they exist.
-a README.md with a text description must exist in the resource's subdirectory for the
+in a specified module directory and will inject PowerShell help files for each resource.
+These help files include details on the property types for each resource, as well as a text
+description and examples where they exist.
+
+The help files are output to the OutputPath directory if specified, or if not, they are
+output to the releveant resource's 'en-US' directory.
+
+A README.md with a text description must exist in the resource's subdirectory for the
 help file to be generated.
+
 These help files can then be read by passing the name of the resource as a parameter to Get-Help.
 
 .PARAMETER ModulePath
-
 The path to the root of the DSC resource module (where the PSD1 file is found, not the folder for
 each individual DSC resource)
 
 .EXAMPLE
-
 This example shows how to generate help for a specific module
 
     New-DscResourcePowerShellHelp -ModulePath C:\repos\SharePointdsc
@@ -58,7 +59,11 @@ function New-DscResourcePowerShellHelp
     (
         [parameter(Mandatory = $true)]
         [System.String]
-        $ModulePath
+        $ModulePath,
+
+        [parameter()]
+        [System.String]
+        $OutputPath
     )
 
     Import-Module (Join-Path -Path $PSScriptRoot -ChildPath 'MofHelper.psm1') -Verbose:$false
@@ -135,7 +140,16 @@ function New-DscResourcePowerShellHelp
                 Write-Warning -Message ($script:localizedData.NoExampleFileFoundWarning -f $result.FriendlyName)
             }
 
-            $savePath = Join-Path -Path $mofFileObject.DirectoryName -ChildPath "\en-US\about_$($result.FriendlyName).help.txt"
+            # Output to $OutputPath if specified or the resource 'en-US' directory if not.
+            $outputFileName = "about_$($result.FriendlyName).help.txt"
+            if ($OutputPath)
+            {
+                $savePath = Join-Path -Path $OutputPath -ChildPath $outputFileName
+            }
+            else
+            {
+                $savePath = Join-Path -Path $mofFileObject.DirectoryName -ChildPath 'en-US' | Join-Path -ChildPath $outputFileName
+            }
             Write-Verbose -Message ($script:localizedData.OutputHelpDocumentMessage -f $savePath)
             $output | Out-File -FilePath $savePath -Encoding utf8 -Force
         }

Tests/Unit/DscResource.DocumentationHelper.Tests.ps1

@@ -924,7 +924,7 @@ Configuration CertificateExport_CertByFriendlyName_Config
         $mockGitUserEmail = '[email protected]'
         $mockGitUserName = 'mock'
         $mockGithubAccessToken = '1234567890'
-        $mockPath = "C:\Windows\Temp"
+        $mockPath = $env:temp
         $mockJobId = 'imy2wgh1ylo9qcpb'
         $mockBuildVersion = '2.1.456.0'
         $mockapiUrl = 'https://ci.appveyor.com/api'
@@ -1383,6 +1383,7 @@ Configuration Example
     $script:mockReadmePath = Join-Path -Path $script:mockSchemaFolder -ChildPath 'readme.md'
     $script:mockOutputFile = Join-Path -Path $script:mockOutputPath -ChildPath "$($script:mockResourceName).md"
     $script:mockSavePath = Join-Path -Path $script:mockModulePath -ChildPath "DscResources\$($script:mockResourceName)\en-US\about_$($script:mockResourceName).help.txt"
+    $script:mockOutputSavePath = Join-Path -Path $script:mockOutputPath -ChildPath "about_$($script:mockResourceName).help.txt"
     $script:mockGetContentReadme = '# Description
 
 The description of the resource.'
@@ -1455,6 +1456,10 @@ Configuration Example
             $InputObject -eq $script:mockPowerShellHelpOutput -and
             $FilePath -eq $script:mockSavePath
         }
+        $script:outFileOutputInputObject_parameterFilter = {
+            $InputObject -eq $script:mockPowerShellHelpOutput -and
+            $FilePath -eq $script:mockOutputSavePath
+        }
         $script:writeWarningDescription_parameterFilter = {
             $Message -eq ($script:localizedData.NoDescriptionFileFoundWarning -f $mockResourceName)
         }
@@ -1465,6 +1470,10 @@ Configuration Example
         $script:newDscResourcePowerShellHelp_parameters = @{
             ModulePath = $script:mockModulePath
         }
+        $script:newDscResourcePowerShellHelpOutput_parameters = @{
+            ModulePath = $script:mockModulePath
+            OutputPath = $script:mockOutputPath
+        }
 
         Context 'When there is no schemas found in the module folder' {
             BeforeAll {
@@ -1621,7 +1630,7 @@ Configuration Example
                 }
         }
 
-        Context 'When there is one schema found in the module folder and one example using .EXAMPLE' {
+        Context 'When there is one schema found in the module folder and one example using .EXAMPLE and the OutputPath is specified' {
             BeforeAll {
                 Mock `
                     -CommandName Get-ChildItem `
@@ -1654,8 +1663,105 @@ Configuration Example
                     -MockWith { $script:mockExampleContent }
 
                 Mock `
+                    -CommandName Out-File
+
+                Mock `
+                    -CommandName Write-Warning `
+                    -ParameterFilter $script:writeWarningExample_parameterFilter
+
+                Mock `
+                    -CommandName Write-Warning `
+                    -ParameterFilter $script:writeWarningDescription_parameterFilter
+            }
+
+            It 'Should not throw an exception' {
+                { New-DscResourcePowerShellHelp @script:newDscResourcePowerShellHelpOutput_parameters } | Should -Not -Throw
+            }
+
+            It 'Should produce the correct output' {
+                Assert-MockCalled `
                     -CommandName Out-File `
-                    -ParameterFilter $script:outFile_parameterFilter
+                    -ParameterFilter $script:outFileOutputInputObject_parameterFilter `
+                    -Exactly -Times 1
+            }
+
+            It 'Should call the expected mocks ' {
+                Assert-MockCalled `
+                    -CommandName Get-ChildItem `
+                    -ParameterFilter $script:getChildItemSchema_parameterFilter `
+                    -Exactly -Times 1
+
+                Assert-MockCalled `
+                    -CommandName Get-MofSchemaObject `
+                    -ParameterFilter $script:getMofSchemaObjectSchema_parameterfilter `
+                    -Exactly -Times 1
+
+                Assert-MockCalled `
+                    -CommandName Test-Path `
+                    -ParameterFilter $script:getTestPathReadme_parameterFilter `
+                    -Exactly -Times 1
+
+                 Assert-MockCalled `
+                    -CommandName Get-Content `
+                    -ParameterFilter $script:getContentReadme_parameterFilter `
+                    -Exactly -Times 1
+
+                Assert-MockCalled `
+                    -CommandName Get-ChildItem `
+                    -ParameterFilter $script:getChildItemExample_parameterFilter `
+                    -Exactly -Times 1
+
+                Assert-MockCalled `
+                    -CommandName Get-DscResourceHelpExampleContent `
+                    -ParameterFilter $script:getDscResourceHelpExampleContent_parameterFilter `
+                    -Exactly -Times 1
+
+                Assert-MockCalled `
+                    -CommandName Write-Warning `
+                    -ParameterFilter $script:writeWarningExample_parameterFilter `
+                    -Exactly -Times 0
+
+                Assert-MockCalled `
+                    -CommandName Write-Warning `
+                    -ParameterFilter $script:writeWarningDescription_parameterFilter `
+                    -Exactly -Times 0
+            }
+        }
+
+        Context 'When there is one schema found in the module folder and one example using .EXAMPLE and the OutputPath is not specified' {
+            BeforeAll {
+                Mock `
+                    -CommandName Get-ChildItem `
+                    -ParameterFilter $script:getChildItemSchema_parameterFilter `
+                    -MockWith { $script:mockSchemaFiles }
+
+                Mock `
+                    -CommandName Get-MofSchemaObject `
+                    -ParameterFilter $script:getMofSchemaObjectSchema_parameterfilter `
+                    -MockWith { $script:mockGetMofSchemaObject }
+
+                Mock `
+                    -CommandName Test-Path `
+                    -ParameterFilter $script:getTestPathReadme_parameterFilter `
+                    -MockWith { $true }
+
+                Mock `
+                    -CommandName Get-Content `
+                    -ParameterFilter $script:getContentReadme_parameterFilter `
+                    -MockWith { $script:mockGetContentReadme }
+
+                Mock `
+                    -CommandName Get-ChildItem `
+                    -ParameterFilter $script:getChildItemExample_parameterFilter `
+                    -MockWith { $script:mockExampleFiles }
+
+                Mock `
+                    -CommandName Get-DscResourceHelpExampleContent `
+                    -ParameterFilter $script:getDscResourceHelpExampleContent_parameterFilter `
+                    -MockWith { $script:mockExampleContent }
+
+                Mock `
+                    -CommandName Out-File
 
                 Mock `
                     -CommandName Write-Warning `
@@ -1693,7 +1799,7 @@ Configuration Example
                     -ParameterFilter $script:getTestPathReadme_parameterFilter `
                     -Exactly -Times 1
 
-                 Assert-MockCalled `
+                Assert-MockCalled `
                     -CommandName Get-Content `
                     -ParameterFilter $script:getContentReadme_parameterFilter `
                     -Exactly -Times 1