Failure at Generating Markdown Files build stage

[SQLCanuck]

The execution of New-MarkdownHelp fails as it is unable to find the imported module.

Expected Behavior

Module imported in during the build ImportModuleManifest stage is recognized by PlatyPS and the documentation generated.

Current Behavior

The build false with the following error:

ERROR: Module TestModule is not imported in the session. Run 'Import-Module TestModule'. At C:\Program Files\WindowsPowerShell\Modules\platyPS\0.12.0\platyPS.psm1:261 char:25

• … throw "Module $_ is not imported in the session. Run 'Imp …

Possible Solution

If I instead add an Import-Module for my psm1 file before New-MarkdownHelp , the documentation is generated but then fails on the GUID as the psd1 is not loaded.

Steps to Reproduce

Created a new module which includes PlatyPS documentation. Ran a build.

Context (Environment)

Windows 11 PowerShell 7.4.5

[SQLCanuck]

Found the source of the issue, though that itself leads to another problem.

The script analyzer gives an error if FunctionsToExport = *, which is the default after the psd1 is generated by Catesta. I had changed this per the Analyzer recommendation to an empty array FuctionsToExport = @(), which resulted in the PlatyPS issue.

An extra build step may be required to update the FunctionsToExport in the modules source psd1.

[SamErde]

You nailed it.

PlatyPS doesn't fail very gracefully, and calling it from other modules sometimes obfuscates the error even more.

Populate that array of functions to export, and assuming there are no other issues, you'll get past this document build task!

Another way to test and get familiar with the process is to run PlatyPS directly to make sure it works, then go back and run the Invoke-Build script.

It might help to add a check early in the build script that fails out right away if FunctionsToExport is still an asterisk or an empty array.

[SQLCanuck]

Adding the following build task has corrected the issue for me, without requiring manual intervention.

#Updates the array for FunctionsToExport in the module manifest
Add-BuildTask UpdateFunctionsToExport -Before TestModuleManifest {
    Write-Build White '      Running module manifest update FuctionsToExport...'
    $publicFunctionPath = Join-Path -Path $script:ModuleSourcePath -ChildPath 'Public'
    $publicFunctions = Get-ChildItem -Path $publicFunctionPath -Filter '*.ps1' -Recurse
    Update-ModuleManifest -Path $script:ModuleManifestFile -FunctionsToExport $publicFunctions.BaseName
    Write-Build Green '      ...Module Manifest Update FunctionsToExport Complete!'
} #UpdateFunctionsToExport

[SamErde]

Nice! Did you put that right before the task that imports the manifest?

# Synopsis: Import the current module manifest file for processing
Add-BuildTask TestModuleManifest -Before ImportModuleManifest {
    Write-Build White '      Running module manifest tests...'
    Assert-Build (Test-Path $script:ModuleManifestFile) 'Unable to locate the module manifest file.'
    Assert-Build (Test-ManifestBool -Path $script:ModuleManifestFile) 'Module Manifest test did not pass verification.'
    Write-Build Green '      ...Module Manifest Verification Complete!'
}

[SQLCanuck]

@SamErde Yes, I placed it right between the build tasks ValidateRequirements and TestModuleManifest.

[SamErde]

@techthoughts2, any interest in a PR with this?

[techthoughts2]

By default, manifests are created with a wildcard in the FunctionsToExport parameter. This violates one of the PSScriptAnalyzer checks and will require you to change it to contain the functions you want to export.

RuleName                            Severity     ScriptName Line  Message
--------                            --------     ---------- ----  -------
PSUseToExportFieldsInManifest       Warning      tbd.psd1   72    Do not use wildcard or $null in this field. Explicitly
                                                                  specify a list for FunctionsToExport.

ERROR:       One or more PSScriptAnalyzer errors/warnings where found.

This is covered in the Catesta FAQ.

| I had changed this per the Analyzer recommendation to an empty array FuctionsToExport = @() Instead of populating the FunctionsToExport parameter with your public function(s), you've given it an empty array. This means that your module will export nothing. Since there are no functions to build help for, platyPS is throwing an exception. You've bypassed the PSScriptAnalyzer check for wildcard, but are instead feeding the build no public functions to build.

FunctionsToExport should contain a list of the public functions you want to export from your module.

I agree that a null check should be added to verify that FunctionsToExport and CmdletsToExport are both not null.