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 = '...'
        }
        #...
    )
}
Advertisements
  1. Leave a comment

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: