One of the really handy improvevements in Powershell V2 is around creating help information for your script users. I often find myself having to read through script and function definitions to figure out how to use them (and this is for scripts I write!), which becomes a real pain as your functions libraries grow. Starting in version 2 we can use comment-based help in function or scripts.
Comment-based help is great for creating simple help information for scripts and smaller collections of functions, however for large groups of functions you should consider using external help files. The format of the external help files is called Microsoft Assistant Markup Langauge (MAML). The XML-based, MAML help file format is used by compiled snapins and modules to produce all of the wonderful help information you see when you type get-help <command name>.
Using external help files provide several benefits over comment-based help:
- Changes in help files do not require changing your script files
- Use language settings
- Easily create HTML or CHM standalone help documention
For the reasons above and since my CodePlex project, SQL Server Powershell Extensions contains over 100 functions, I've decided to create all of my help documentation in MAML files. For compiled cmdlets there is a very nice utility called Cmdlet Help Editor by Wassim Fayed that autogenerates MAML files. Unfortunately the utility does not work for scripts, so, I created a script called New-MAML that accepts either CommandInfo or FunctionInfo objects emitted from Get-Command. The New-MAML script is posted on Poshcode.
New-MAML uses a function called New-XML created by Joel Bennet. The New-XML function leverages LINQ to make quick work out of generating XML documents, in this case a MAML file. Here's an example of using the New-MAML script for a function called Test-ISpath that is part of the SSIS related functions provided in SQLPSX:
Having sourced the function test-ispath, call the New-MAML function:
$xml = ./new-maml test-ispath
$xml.Declaration.ToString() | out-file ./test-ispath.ps1-help.xml -encoding "UTF8"
$xml.ToString() | out-file ./test-ispath.ps1-help.xml -encoding "UTF8" -append
$xml.Declaration.ToString() | out-file ./test-ispath.ps1-help.xml -encoding "UTF8"
$xml.ToString() | out-file ./test-ispath.ps1-help.xml -encoding "UTF8" -append
Once the XML/MAML file is generated, you'll need to manually edit the MAML by filling in the TODO items and the parameters options that are defaulted to false. The position parameter option will need to be changed in the generated MAML also. For compiled cmdlets place the MAML file in the same directory as the binary module or snapin dll. For script modules/functions include a reference to the External MAML file for each function. Unfortunately script modules require that you specify the path to your MAML for EVERY function. Note: You can have multiple function help items within the same MAML file.
Finally edit the the Test-IsPath function by adding the path to your XML file.
# .ExternalHelp C:\Users\u00\bin\Test-ISPath.psm1-help.xml
function Test-ISPath
function Test-ISPath
..Rest of function ...
Note: when you specify an external help file, you need to use an absolute path (except for language subfolder) with no variables as part of the path name. For instance I'll often use $scriptRoot = Split-Path (Resolve-Path $myInvocation.MyCommand.Path) in my scripts, however this will NOT work:
# .ExternalHelp $scriptRoot\Test-ISPath.psm1-help.xml
Interestingly enough, you will still get default help generated even though it will fail to use the help file.
Having specified an absolute path, if you re-source the function or reload the module you'll be able to call get-help test-ispath
