platyPS
platyPS copied to clipboard
PowerShell
Generate Help From Publish-able powershell script
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
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.
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.
@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?
@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
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?
@vors I have powershell experience but I've never done a pull. I'm happy to give it a shot though!
@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/
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
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.
@theJasonHelmick @adityapatwardhan I marked this as consider for 2.0 since there is a PR open to fix the problem.
Implementation in PR for the v2 for New-MarkdownHelp seems to have resolved this issue: https://github.com/PowerShell/platyPS/pull/520
I do not have dates for the next release though, hopefully soon.
There are a few issues being described in this issue.
- Getting help for all of the functions in the script
- Include information from the
<#PSScriptInfo #>comment block
Answers
-
Get-Helpis only showing the help content from the first comment-based help block because of its position in the source file. For a script,Get-Helpthinks 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. - 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.