Generate Help From Publish-able powershell script

[darksidemilk]

So say I have a script that I have made publishable, and it's something that doesn't make sense to be its own module. So I've utilized the powershell command New-scriptfileinfo to create the proper headers including a top level help comment block. Then the script also has various functions each with a comment block.
If I try to import the script it runs the script,
Since I am able to add a .link parameter I figure it would be nice to create md files for hosting at the site I put said link.

So in short, Is it possible to use playtps to generate file from a normal ps1 file, or something of that sort.

Here's a little more info with an example.

Here's the heading of a script I use for firstlogoncommands that's launched via an unattend.xml in the oobe phase of sysprep.

<#PSScriptInfo
    .VERSION
        8.1.0
    .GUID
        the-generated-gui-id-goeshere
    .AUTHOR
        JJ Fullmer
    .COMPANYNAME
        My Company
    .COPYRIGHT
        2018
    .TAGS
        Automating-Imaging, IT-2040, sysprep, after-image, oobe, unattend.xml, firstlogon, setup,
        IT-2057, imaging, provisioning, chocolatey
    .LICENSEURI
    .PROJECTURI
        https://InternalKBSite.domain.com/First+Logon+Commands
    .ICONURI
    .EXTERNALMODULEDEPENDENCIES
    .REQUIREDSCRIPTS
        Update-Bootmgr fixwsus cocopuffs
    .EXTERNALSCRIPTDEPENDENCIES
    .RELEASENOTES
        8.1.0
            IT-2040 #comment added error checking with try catch blocks
        8.0.4
            IT-2057 #comment updated firstlogon to use published fixwsus script
            IT-2040 #comment added psrepository configuration at start of script
                also updated userrights script installation to be proper;
        8.0.3
            IT-2040 #comment update to 8.0.3 install the cocopuffs script and run it natively
        8.0.2
            IT-2040 #comment Updated set-bootmgr to use external script
        8.0.1
            * Fixed secondlogon runner as it was only installing it and not setting it to start
        8.0
            * Made Published version
            * Updated second-logon enabler to use published version of second logon scripts
            * Commented out copying itself to c drive
            * Will have to take out references to arrowfs4 share paths as those get published
            * Moved script to _scripts folder
            * Created class for autologon keys instead of storing them in plaintext
#>

<#
    .SYNOPSIS
        Script to run at first logon, is run via the oobe pass of sysprep

    .DESCRIPTION
        This script is started by the oobe pass of sysprep and finishes configuring everything
        It completes configuration of things like
            3of9 barcode font
            provisioning packages
                hide oobe
                certificates
            activates windows
            windows features customization
            setup time server settings
            firewall settings
            add drivers
            install chocolatey
            install fogservice
        Deletes any temporary files
        disables administrator autologon
        sets up schtask for secondlogonscript

    .LINK
         https://InternalKBSite.domain.com/First+Logon+Commands

#>

Then there are various functions defined each with their own help block. Then a main function is called.
Once this script is installed via install-script firstlogoncommands -repository internalRepo it is added to the powershell scripts folder that is added to the PATH the first time a script is installed. So if I run get-help firstlogoncommands it shows the second comment block with the standard help block info.

I'm also wondering if the information such as the release notes, version author, etc. could also be converted to markdown as part of generating the help file.

Thanks,
-JJ

[vors]

The PSScriptInfo block would need some special handling.
For other stuff, if you dot-source the script block and then call New-MarkdownHelp -Command ... you should be able to generate the markdown just fine. Let me know if you encounter any problems with it.

[Geogboe]

I too have this question. Any help greatly appreciated!

Edit Removed previous comment as I had misunderstood the instruction.

Last Edit :)

I didn't have to install the module first. While platyps threw an error it threw an error it seemed to still generate the markdown when I called it like this:

New-MarkdownHelp -Command ".\scripts\my-script.ps1" -OutputFolder .\docs\ -force

I didn't have to dot source the script or anything.

[darksidemilk]

@Geogboe that is some good information. In said script where that worked where is your help block? Do you use the PSScriptInfo block at all for publishing scripts?

[Geogboe]

@darksidemilk Yep, I had the psscriptinfo block. I'll provide some more details below:

Sample script

<#PSScriptInfo

.VERSION 0.0.1
.GUID 23092348203842390
.AUTHOR Me
.COMPANYNAME Companay
.COPYRIGHT Now
.TAGS script
.LICENSEURI MIT
.PROJECTURI
.ICONURI
.EXTERNALMODULEDEPENDENCIES
.REQUIREDSCRIPTS
.EXTERNALSCRIPTDEPENDENCIES
.RELEASENOTES
- v0.0.1 - initial release
.PRIVATEDATA

#>

<#
.SYNOPSIS
    does stuff
.DESCRIPTION
    even more
.EXAMPLE
    .\my-script.ps1 -path $pwd

    Will test the path provided by $pwd and return true or false
#>

[cmdletbinding( PositionalBinding )]
param (

    [Parameter( Mandatory )]
    [string]
    $Path

)

Test-Path $Path

Command output

New-MarkdownHelp -Command ".\my-script.ps1" -Force -OutputFolder .\docs\
Get-Command : The term 'my-script.ps1' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the
name, or if a path was included, verify that the path is correct and try again.
At C:\Program Files\WindowsPowerShell\Modules\platyPS\0.12.0\platyPS.psm1:211 char:58
+ ...                      $helpFileName = GetHelpFileName (Get-Command @a)
+                                                           ~~~~~~~~~~~~~~
    + CategoryInfo          : ObjectNotFound: (my-script.ps1:String) [Get-Command], CommandNotFoundException
    + FullyQualifiedErrorId : CommandNotFoundException,Microsoft.PowerShell.Commands.GetCommandCommand

    Directory: C:\docs


Mode                LastWriteTime         Length Name
----                -------------         ------ ----
-a----       11/28/2018   1:01 PM           1001 my-script.ps1.md

Despite the error the markdown document is created and looks right

[vors]

Hm, very interesting. Indeed it's an external command.

PS > Get-Command ./foo.ps1

CommandType     Name                                               Version    Source
-----------     ----                                               -------    ------
ExternalScript  foo.ps1                                                       /foo.ps1

@Geogboe @darksidemilk would you care to fix platyPS to avoid throwing error in this case and send a pull request?

[Geogboe]

@vors I have powershell experience but I've never done a pull. I'm happy to give it a shot though!

[Geogboe]

@vors I looked through the code and it looks like the error is being thrown only when platy is trying to come up with a name for the markdown file it's going to create.

Right now, platy successfully finds and loads the command ( .\my-script.ps1 ) but then passes only the name of the script ( not included the relative path ) to Get-Command to generate the file name. `Get-Command will not search the current working directory so will through a non-terminating error it seems.

The most straightforward solution seemed to be, check if this command is an external script and if so, make sure we resolve the path ( relative to us ) and pass THAT to get-command.

I'm not sure I fully understand the core of platy yet though so this may just be a work around solution rather than a full solution. Just let me know though.

5 tests failed but those same 5 tests failed before I made the change so I think that's unrelated.
Pull request here: https://github.com/PowerShell/platyPS/pull/

[michalzobec]

Hello @Geogboe ,

I have same problem as describe @darksidemilk . I have similiar script with help

<#
.SYNOPSIS
Scan Updates Offline
Perform an offline scan using Windows Update Agent (WUA) and PowerShell.
Script supports run locally with Administrator rights.

.DESCRIPTION
Scan Updates Offline
Copyright (c) 2019 Michal Zobec, ZOBEC Consulting. All Rights Reserved.
Portions (c) 2018-2019 Andrei Stoica. All Rights Reserved.
web: www.michalzobec.cz, mail: [email protected]
GitHub repository http://zob.ec/xxxx
License: Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)

.OUTPUTS
Scan result will be stored in log file.

.PARAMETER ScanInstalledUpdates
Performs scan only of installed updates in system. Result of scan will be stored in log file.

.PARAMETER ScanMissingUpdates
Performs scan only of missing updates in system. Result of scan will be stored in log file.

.EXAMPLE
C:> Scan-UpdatesOffline.ps1

.EXAMPLE
C:> Scan-UpdatesOffline.ps1 -ScanInstalledUpdates
Performs scan only of installed updates in system. Result of scan will be stored in log file.

.EXAMPLE
C:> Scan-UpdatesOffline.ps1 -ScanMissingUpdates
Performs scan only of missing updates in system. Result of scan will be stored in log file.

.NOTES
Twitter: @michalzobec
Blog : http://www.michalzobec.cz

.LINK
About this script on my Blog in Czech
http://zob.ec/xxxxblog
#>

Actually I not have implemented support of commandline parameters because I working now with technical demo. But I expect generation of help from script.

And I have same problem with error messages if I will try use New-MarkdownHelp command:

PS D:\work\scripts\Infrastructure-Pack\Microsoft-Update-Offline-Solution\Microsoft-Update-Offline-Scan> New-MarkdownHelp -Command ".\Scan-UpdatesOffline.ps1" -OutputFolder ".\help"
Get-Command : The term 'Scan-UpdatesOffline.ps1' is not recognized as the name of a cmdlet, function, script file, or o
perable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try aga
in.
At C:\Program Files\WindowsPowerShell\Modules\platyPS\0.14.0\platyPS.psm1:2360 char:17

•     return (Get-Command $help.Name -Syntax) -eq ($help.Synopsis)
  

•             ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  

  • CategoryInfo : ObjectNotFound: (Scan-UpdatesOffline.ps1:String) [Get-Command], CommandNotFoundException
  • FullyQualifiedErrorId : CommandNotFoundException,Microsoft.PowerShell.Commands.GetCommandCommand

  Directory: D:\work\scripts\Infrastructure-Pack\Microsoft-Update-Offline-Solution\Microsoft-Update-Offline-Scan\help

Mode LastWriteTime Length Name

---

-a---- 03.07.2019 2:00 795 Scan-UpdatesOffline.ps1.md

[danielfeiler]

We also ran in this issue.
It occurs because get-command do not look for a file in filesystem if it's path is not either specified absolute or relative.
the $help.Name contains only the scriptname without path.
a workaround is to do the following:
$command = get-command .\YourScript.ps1
$sb= $command | select -ExpandProperty ScriptBlock
$null=New-Item "Function:\$($command.Name)" -Value $sb
New-MarkdownHelp -Command $($command.Name) -OutputFolder $docpath -Force
$null=Remove-Item "Function:\$($command.Name)"
I've also have fixed it in the module for me. I will send a pull request for this changes.

[sdwheeler]

@theJasonHelmick @adityapatwardhan I marked this as consider for 2.0 since there is a PR open to fix the problem.

[adityapatwardhan]

Implementation in PR for the v2 for New-MarkdownHelp seems to have resolved this issue: #520

I do not have dates for the next release though, hopefully soon.

[michalzobec]

thank you, I will happy for this release :)

[sdwheeler]

There are a few issues being described in this issue.

1. Getting help for all of the functions in the script
2. Include information from the <#PSScriptInfo #> comment block

Answers

1. Get-Help is only showing the help content from the first comment-based help block because of its position in the source file. For a script, Get-Help thinks that comment block contains the help for the script and not a function in the script. It displays that content as the help for the script. For best results, comment-based help for a function should be located inside the function block. Also, you will only get help for the individual functions if you dot source the script file.
2. Providing information from the <#PSScriptInfo #> comment block in help requires changes to PowerShell's help system. The <#PSScriptInfo #> comment block would have to be parsed and added to the help object model.