diff --git a/CHANGELOG.md b/CHANGELOG.md index 39d7b25..cc592c7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Fixed + +- `Generate_Markdown_For_Public_Commands.build` + - Now the task will not try to generate markdown if the module does not + have any publicly exported commands ([issue #135](https://github.com/dsccommunity/DscResource.DocGenerator/issues/147)). + - Now has error handling if the script that is called using the call + operator `&` fails. +`Generate_External_Help_File_For_Public_Commands` + - Now the task will not fail if there are no extern help file generated, + which is the case for modules that does not have any publicly exported + commands ([issue #135](https://github.com/dsccommunity/DscResource.DocGenerator/issues/147)). + - Now has error handling if the script that is called using the call + operator `&` fails. + ## [0.12.2] - 2024-05-31 ### Added diff --git a/source/tasks/Generate_External_Help_File_For_Public_Commands.build.ps1 b/source/tasks/Generate_External_Help_File_For_Public_Commands.build.ps1 index 4455829..164d1fb 100644 --- a/source/tasks/Generate_External_Help_File_For_Public_Commands.build.ps1 +++ b/source/tasks/Generate_External_Help_File_For_Public_Commands.build.ps1 @@ -116,6 +116,22 @@ New-ExternalHelp -Path '$DocOutputFolder' -OutputPath '$builtModuleLocalePath' - #> & $pwshPath -Command $generateMarkdownScriptBlock -ExecutionPolicy 'ByPass' -NoProfile - # Add a newline to the end of the help file to pass HQRM tests. - Add-NewLine -FileInfo (Get-Item -Path "$builtModuleLocalePath/$ProjectName-help.xml") -AtEndOfFile + if (-not $?) + { + throw "Failed to generate external help file for the module '$ProjectName'." + } + + $externalHelpFile = Get-Item -Path (Join-Path -Path $builtModuleLocalePath -ChildPath "$ProjectName-help.xml") -ErrorAction 'Ignore' + + if ($externalHelpFile) + { + # Add a newline to the end of the help file to pass HQRM tests. + Add-NewLine -FileInfo $externalHelpFile -AtEndOfFile + + Write-Build -Color 'Green' -Text "External help file generated for the module '$ProjectName'." + } + else + { + Write-Warning -Message "External help file not found at '$builtModuleLocalePath/$ProjectName-help.xml'. This is normal if there were no exported commands in the module." + } } diff --git a/source/tasks/Generate_Markdown_For_Public_Commands.build.ps1 b/source/tasks/Generate_Markdown_For_Public_Commands.build.ps1 index 781d560..0c3e7c9 100644 --- a/source/tasks/Generate_Markdown_For_Public_Commands.build.ps1 +++ b/source/tasks/Generate_Markdown_For_Public_Commands.build.ps1 @@ -166,8 +166,19 @@ Import-Module -name '$DependentModule' } $generateMarkdownScript += @" -`n# Import the module to generate help for -Import-Module -Name '$ProjectName' -ErrorAction Stop +`n# Import the module that help is generate for +`$importModule = Import-Module -Name '$ProjectName' -Passthru -ErrorAction 'Stop' + +if (-not `$importModule) +{ + throw 'Failed to import the module ''$ProjectName''.' +} +elseif (`$importModule.ExportedCommands.Count -eq 0) +{ + Write-Warning -Message 'No public commands found in the module ''$ProjectName''. Skipping' + + return +} `$newMarkdownHelpParams = @{ Module = '$ProjectName' @@ -200,4 +211,13 @@ New-MarkdownHelp @newMarkdownHelpParams other modules that are loaded in the current process. #> & $pwshPath -Command $generateMarkdownScriptBlock -ExecutionPolicy 'ByPass' -NoProfile + + if (-not $?) + { + throw "Failed to generate markdown documentation for the public commands for module '$ProjectName'." + } + else + { + Write-Build -Color 'Green' -Text 'Markdown for command documentation created for module '$ProjectName'.' + } } diff --git a/tests/unit/tasks/Generate_External_Help_File_For_Public_Commands.Tests.ps1 b/tests/unit/tasks/Generate_External_Help_File_For_Public_Commands.Tests.ps1 index 8ab5f7c..de70823 100644 --- a/tests/unit/tasks/Generate_External_Help_File_For_Public_Commands.Tests.ps1 +++ b/tests/unit/tasks/Generate_External_Help_File_For_Public_Commands.Tests.ps1 @@ -138,4 +138,31 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable Should -Exist -ActualValue (Join-Path -Path $TestDrive.FullName -ChildPath 'en-US/MockModule-help.xml') -Because 'the task should have generated the external help file from the markdown.' } + + Context 'When there is no external help file created' { + It 'Should run the build task without throwing' { + Mock -CommandName Write-Warning + Mock -CommandName Get-Item -ParameterFilter { + $Path -eq (Join-Path -Path $TestDrive.FullName -ChildPath 'en-US/MockModule-help.xml') + } -MockWith { + return $null + } + + { + $taskParameters = @{ + ProjectName = 'MockModule' + ProjectPath = $TestDrive.FullName + OutputDirectory = $TestDrive.FullName + # Using the markdown created when the project was built. + DocOutputFolder = $TestDrive.FullName | Join-Path -ChildPath 'WikiContent' + SourcePath = "$($TestDrive.FullName)/source" + HelpCultureInfo = 'en-US' + } + + Invoke-Build -Task $buildTaskName -File $script:buildScript.Definition @taskParameters + } | Should -Not -Throw + + Assert-MockCalled -CommandName Write-Warning -Exactly -Times 1 -Scope It + } + } }