New-MarkdownHelp example 1 fails if executed within script

[iricigor]

Steps to reproduce

Create a script equivalent to New-MarkdownHelp example 1, name it Example1.ps1 and execute it.

# Example1.ps1
function Command03 {param([string]$Value)}
New-MarkdownHelp -Command "Command03" -OutputFolder ".\docs"

Expected behavior

Script will create Command03.md file.

Actual behavior

Script fails because it cannot find Command03, although command exists in the session.

Command existence can be confirmed with running Get-Command Command03 before New-MarkdownHelp

Environment data

PowerShell version 5.1 on Windows or PowerShell 6.1 on Ubuntu PlatyPS v.0.11.1

Comments

Error points to this line.

Issue seems to be related to PowerShell script scope, as running those two commands in interactive session generates expected result. The same problem is impacting also Update-MarkdownHelp in the same scenario. Cmdlets imported via modules, or in interactive sessions are not affected.

This effectively blocks automated tests or deployments of cmdlets which are not part of module (standalone scripts).

Any suggestions how to overcome this problem?

[vors]

Interesting. As a workaround you can dot-source the file, that works.

[iricigor]

Ok, correct in given example. But here is my full use case

# MyCommand.ps1
function Command03 {param([string]$Value)}

I want to check if I have proper documentation during build process. The same works fine for modules.

# Documentation.Tests.ps1

. .\MyCommand.ps1
Describe "Proper Command Documentation" {

    It "Command should exist" {
        Get-Command Command03 -ea 0 | Should -Not -Be $null
        Get-Command FakeCommand -ea 0 | Should -Be $null
    }

    It 'Updates documentation and finds no diff' {
        New-MarkdownHelp -Command Command03 -Force -OutputFolder . -wa 0
        $diff = git diff .\Command03.md
        $diff | Should -Be $null
    }
}

So, if I run this as .\Documentation.Tests.ps1 it fails as explained above.

Like you mentioned, dot-sourcing it as . .\Documentation.Tests.ps1 works fine. Also renaming MyCommand.ps1 to MyCommand.psm1 and importing it with Import-Module .\MyCommand.psm1 works fine. Whatever brings command to "global scope", works fine.

But, I am starting this script with Invoke-Pester and I cannot really dot-source it :disappointed:

[iricigor]

And now that I think more of it, this looks like PowerShell issue...

# define standalone and module function
function MyComm {}
New-Module -ScriptBlock {function FindMyComm {Get-Command MyComm}} | Import-Module

# check for both functions
Get-Command MyComm
Get-Command FindMyComm

# run new function
FindMyComm

[vors]

Yeap, we had to work around quite a few PowerShell quirks in platyPS, but mostly related to the help system. Perhaps we can find some workaround here as well... Would you mind to open an issue on https://github.com/PowerShell/PowerShell ?

[iricigor]

Issue in PowerShell repository is opened and linked above.

For my use case I implemented workaround to define my function as global. Then all works fine. Would this be worth mentioning it somewhere, or the issue here can just be closed?

# Example1.ps1
function Global:Command03 {param([string]$Value)}
New-MarkdownHelp -Command "Command03" -OutputFolder ".\docs"

[vors]

Hm, yeah we can probably create FAQ.md and add such edge cases there.

[sdwheeler]

This is fixed in platyps v0.14.