Archive for August, 2011

Helps module – PowerShell MAML help builder

In order to create help files for one of my PowerShell modules I did not find any better solution than to invent my own MAML help builder. Here it is:

https://github.com/nightroman/Helps

The module builds PowerShell MAML help files from PowerShell help scripts. Help scripts are almost WYSIWYG, they look very similar to the result help. Still, they are just scripts and this makes a lot of useful features easy. One of them is building help files for several cultures.

The module builds help for cmdlets, functions, scripts, and providers. Here is the template help source script:


<#
.SYNOPSIS
    Template help source script.

.DESCRIPTION
    The help source script returns hashtables describing command/provider help.
    The caller or the script itself should make all the commands available.

    Synopsis, description, remarks, etc. can be strings or string arrays.

    Each string is shown as a new line. Strings with leading tabs or spaces are
    treated as pre-formatted blocks. Other strings are formatted: sequences of
    not empty not indented lines are joined together with single spaces.
#>

### Command help data

<#
* Mandatory keys: 'command', 'synopsis', 'parameters'.
* 'description': the default value is the 'synopsis' text.
* 'sets' keys are parameter set names, values are remarks.
* 'parameters' keys are parameter names, values are remarks.
* 'examples.title': the default is generated: --- EXAMPLE N ---
* 'examples.code': [ScriptBlock] or [string].
    [ScriptBlock] is called by 'test' called by Test-Helps.
* 'examples.test': [ScriptBlock].
    $args[0] is the example code being tested.
#>
@{
    command = 'Name'
    synopsis = '...'
    description = '...'
    sets = @{
        Set1 = '...'
        #...
    }
    parameters = @{
        Param1 = '...'
        #...
    }
    inputs = @(
        @{
            type = '...'
            description = '...'
        }
        #...
    )
    outputs = @(
        @{
            type = '...'
            description = '...'
        }
        #...
    )
    notes = '...'
    examples = @(
        @{
            title = '...'
            introduction = '...'
            code = {
            }
            remarks = '...'
            test = {
                . $args[0]
            }
        }
        #...
    )
    links = @(
        @{
            text = '...'
            URI = '...'
        }
        #...
    )
}

### Provider help data

<#
Provider help items are similar to command help items with same names.
The are a few differences:
* Mandatory keys: 'provider', 'synopsis'.
* 'examples': 'introduction' and 'code' are not joined.
#>
@{
    provider = 'Name'
    drives = '...'
    synopsis = '...'
    description = '...'
    capabilities = '...'
    tasks = @(
        @{
            title = '...'
            description = '...'
            examples = @(
                @{
                    title = '...'
                    introduction = '...'
                    code = {
                    }
                    remarks = '...'
                    test = {
                        . $args[0]
                    }
                }
            )
        }
        #...
    )
    parameters = @(
        @{
            name = '...'
            type = '...'
            description = '...'
            cmdlets = '...'
            values = @(
                @{
                    value = '...'
                    description = '...'
                }
                #...
            )
        }
        #...
    )
    notes = '...'
    links = @(
        @{
            text = '...'
            URI = '...'
        }
        #...
    )
}

Leave a comment