Providing Online Help for Powershell Modules

As a finishing touch for the SQL Server Powershell Extensions 2.0 Release I wanted to provide an online version of the help documentation I created from both comment-based and MAML formats. I had two requirements I need to be able to automatically convert comment-based and MAML-based help into static HTML pages and I need a free place to host the pages. The reason for the latter requirement is that I’m kind of lazy about web hosting. I don’t have my own server and I really don’t have a desire to have my own site–that’s part of the reason I blog at http://chadwickmiller.spaces.live.com. So I need to find a free static web hosting service. But, my first task is to automatically create HTML pages…

Generating Help HTML Pages

My favorite Powershell scripts are the ones I don’t have to write and a great place to find ready-to-use Powershell scripts is PoshCode which hosts a repository of over 1,500 scripts. A quick search of PoshCode turned up a script called Out-Html by Vegard Hamar (whose script in turn is based on a script called Out-Wiki by Dimitry Sotnikov). The script converts help from pssnapin’s to HTML. I need to convert help for function and cmdlets within modules, so I performed a minor edit of Out-Html PoshCode creates a new version of a Powershell script if you modify an existing one. If you do make a useful modification, please consider sharing. This goes for original scripts also.. To use Out-Html I need to import my modules: sqlserver, repl, Agent, SQLParser and ShowMbrs. Next modify the last line of the Out-html script to filter for these modules:

Out-HTML ( get-command | where {($_.modulename -eq 'sqlserver' -or $_.modulename -eq 'repl' -or `
$_.modulename -eq 'Agent' -or $_.modulename -eq 'SQLParser' -or $_.modulename -eq 'SSIS' -or $_.modulename -eq 'ShowMbrs') -and $_.commandtype -ne 'Alias'}) $outputDir

Finally, run Out-Html:

./Out-Html

And viola, 126 html files are produced in a folder named help under the current directory. The HTML files are pretty clean, but do contain a stray bracket, question mark and require some manual editing. Rather tweak the Out-Html script or mess around with Powershell I can easily fix all HTML documents using my favorite text editor, Vim:

  • Select all htm files in Explorer and select edit with single Vim
  • In command mode
args *.htm
argdo %s/”<div>/<div>/ge | update
argdo %s/</table>}/</table>/ge | update

If only Powershell ISE could do stuff like this, I might actually use it Open-mouthed. One other minor edit which I’ll explain in the next section, I need to rename default.htm to index.htm and index.html to default.htm. In addition, change the new index.htm line frame src=”./default.htm”. Having generated 126 HTML pages, I now need to find a place to host them…

Hosting Help HTML Pages

While searching for a place to plunk down my static we pages I found a blog post by Charles Engelke that describes how to use Google AppEngine for web hosting of static web pages–exactly what I’m looking for…

Setting Up a Google Application

To get started I had to perform a few setup tasks:

Testing Google Application

To setup a test/deployment environment on my machine. First I created a directory C:sqlpsx and subdirectory static i.e. C:sqlpsxstatic. I then moved all 126 htm files to the static directory.  Following Charles’ instructions I created an app.yaml file with the contents below and saved the file to C:sqlpsx

application: sqlpsx
version: 1
runtime: python
api_version: 1

handlers:
- url: (.*)/
static_files: static1/index.htm
upload: static/index.htm

- url: /
static_dir: static

The yaml file sets the index file as the default page which is why a swapped default and index file content as described earlier and also specifies the static directory. I’m now ready to test the application using SDK…

Start Google App Engine Launcher which is part of the SDK installed earlier. From the File menu select “Add Existing Application..” and navigate to the C:sqlpsx directory. Then click Run.

AppEngineLauncher

If everything is setup correctly clicking Browse allows me to test the application locally before deploying. Eureka It Works!

Deploying Google Application

Finally deploying the application is as simple as clicking Deploy

SQLPSX Online Help

The website isn’t very pretty, but not bad for a few hours work. The online help site for SQL Server Powershell Extensions is available at http://sqlpsx.appspot.com/. Enjoy!

{ 0 comments… add one }

Leave a Comment


eight + = 13

%d bloggers like this: