Tag Archives: Help

Get-Help for Modules you don’t have installed

If you have you ever wished you could get-help on commands for modules you don’t have installed locally, or are having problems using Save-Help to get module help onto servers that don’t have an internet connection because your clients don’t have those modules — I have a solution.

With the new Update-Help command, the PowerShell team has made it possible to Save-Help to disk, and then move that help and update servers that are offline or behind strict firewalls. However, there’s no built-in way to download help for a module that’s not installed on your local client … and you can’t use the output of Save-Help to read the help on your development box if you don’t have the module installed there.

My new module HelpModules aims to solve both those problems with two commands:

New-HelpModule

New-HelpModule will let you generate a simple module stub that contains just enough information to convince Update-Help and Save-Help to do their jobs. What’s more, it works on the pipeline so you can use Invoke-Command to get the module information from remote servers and pipe it straight into New-HelpModule:

Invoke-Command -ComputerName Server1 {
   Get-Module -ListAvailable | Where HelpInfoUri } | New-HelpModule
 

This example would actually list all the modules from a server named “Server1” that have updatable help, generate stubs for them in your local $PSModuleHelpRoot (more about that later), and update the help files (locally).

You can also generate a stub by hand, given the information about the module. In other words, call your mate up on the phone, have them run Get-Module Hyper-V -List | Format-List * and then read you the GUID, Version, and HelpInfoUri … then, you just run:

New-HelpModule Hyper-V '1.0' 'af4bddd0-8583-4ff2-84b2-a33f5c8de8a7' 'http://go.microsoft.com/fwlink/?LinkId=206726'
 

StubFunctions

The second problem we have is that we can’t run Get-Help on commands that don’t exist on our system. There are two ways around that, using this module. The simplest is to just pass the -StubFunctions switch when you’re calling New-HelpModule. This will generate empty function stubs for each command that’s in the original module — they have no parameters, no code, nothing.

StubFunctions are be enough to let Get-Help work on those commands, but you’ll have to add the $PSModuleHelpRoot to your $Env:PSModulePath in order to take advantage of it. The problem with that is that you’ll pollute your session with modules and commands that don’t really exist (or at least, don’t do anything). Incidentally, I promised more information about PSModuleHelpRoot:

PSModuleHelpRoot

This variable is exported by the HelpModules module, and it’s the path to where New-HelpModule will generate modules (and where Get-ModuleHelp will read from: more on that next). The path defaults to a “WindowsPowerShellHelpModules” folder in your Documents directory, but you can set it to anything you like after importing the module.

Get-ModuleHelp

Get-ModuleHelp is basically a simplified version of Get-Help that works straight on the XML files in your $PSModuleHelpRoot modules. Instead of searching for commands, it searches for help.

It basically works the same as Get-Help, so I’m not going to bother with documentation here — the point is, unlike Get-Help, this doesn’t require you to add $PSModuleHelpRoot to your $Env:PSModulePath, and thus doesn’t add empty modules and commands to your session. It’s a little harder to work with, since you have to know what help you have available, and you have to type the full command name (no wildcard support) but that seemed worth it to me.

Get HelpModules from PoshCode.org (you’ll want to save it as “HelpModules.psm1” to a path in your PSModulePath like: ~\Documents\WindowsPowerShell\Modules\HelpModules\HelpModules.psm1

Rich formatting for PowerShell help

[updated] Ok, I just updated this with a new post on PoshCode. I posted the HtmlHelp module to PoshCode for generating HTML web pages based on the help for functions or cmdlets. It basically has one command: Get-HtmlHelp, which takes a couple of parameters now. The only mandatory parameter is the name of the command you want help for, in this case the html is output on the pipeline and can be redirected into a file.

Get-HtmlHelp Get-HtmlHelp | Set-Content Get-HtmlHelp.html
 

The markup generated is (I hope) reasonable and lightweight, with some simple css rules pre-applied. Feel free to customize the script to generate help however you like.

[new] Generating many at once

I forgot to mention the other parameters on Get-HtmlHelp. They’re pretty cool, because if you want to upload your help you can do so with this. Say you created a module, and you wanted to generate all the help into files for uploading. You want to set the -BaseUrl to the location you will upload them to, and then use the -OutputFolder parameter to generate an html file for each command into the specified folder:

Get-Command -Module ModuleName |
Get-HtmlHelp -BaseUrl http://HuddledMasses.org/HtmlHelp/ -OutputFolder ~\sites\HuddledMasses\HtmlHelp\
 

Now you can just take those files and upload them to the right spot on your website. I actually have some scripts which I can wrap around this to post the help to a wiki, but you’re just going to have to wait for that until the next time I get inspired to work on help …

Show-Help

I did include a little function in the comments and in the help for Get-HtmlHelp which uses ShowUI to display the rich formatted help in a popup window:

function Show-Help {
[CmdletBinding()]
param([String]$Name)  
   Window { WebBrowser -Name wb } -On_Loaded {
      $wb.NavigateToString((Get-HtmlHelp $Name))
      $this.Title = "Get-Help $Name"
   } -Show
}
 

So anyway, enough of that. When you run it, it looks like this (click for the full screenshot):

Click to see full screen-shot