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
If only Powershell ISE could do stuff like this, I might actually use it 
. 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
Setting Up a Google Application
To get started I had to perform a few setup tasks:
- Sign up for a Google App Engine account. As part of the sign up I picked sqlpsx to be the application name.
- Install the latest version of Python from ActiveState. In order to use the static web page hosting method Python is required. Now, I don’t know Python, but fortunately you don’t need to know how to write a single line of Python code to setup static web pages.
- Download and install Google App Engine SDK for Python. The SDK provides a GUI based utility for testing and deploying a Google application.
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:\sqlpsx\static. 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: static\1/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.
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!
