Fix tasks that fail for modules without exported commands (#148)

dsccommunity · Jun 1, 2024 · b451007 · b451007
1 parent 049c1e0
commit b451007
Show file tree

Hide file tree

Showing 4 changed files with 81 additions and 4 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
+        }
+    }
 }