CODEWITHSUNDEEP
powershellmaml
Adam Driscoll
Adam Driscoll

Reputation: 9483

PowerShell MAML Help Generator

Does anyone know of a utility for generating PowerShell cmdlet help files? Doing it by hand seems a bit tedious...

I located: http://blogs.msdn.com/powershell/archive/2007/09/01/new-and-improved-cmdlet-help-editor-tool.aspx

Any updated versions? I can't select a module. I have a binary module.

Upvotes: 6

Views: 4240

Answers (5)

Michael Sorens
Michael Sorens

Reputation: 36768

With the advent of the open-source XmlDoc2CmdletDoc, you can now document your binary PowerShell cmdlets (i.e. those written in C#) just like any other C# libraries, and just like scripted cmdlets (those written in PowerShell): use inline documentation comments.

No longer do you need to maintain a parallel MAML file by hand! Just instrument your build so that when you recompile your C# project it executes the documentation generator and you get both a module.dll and a module.dll-Help.xml. The latter is directly used by PowerShell to provide help on your cmdlets when you invoke Get-Help.

And XmlDoc2CmdletDoc even offers a -strict switch to ensure that you have comprehensively documented your cmdlets; if you use the switch and you missed something, your build will fail, as it should.

Other benefits automatically provided by XmlDoc2CmdletDoc ("sections" in this list refers to the sections of help presented by Get-Help):

  • Each custom type in the Outputs section includes a description.
  • The Syntax section includes possible values for enumerated types.
  • The Parameter section includes possible values for enumerated types.
  • Aliases are documented automatically in the Parameters section.
  • Aliases are treated as first-class parameters so you can ask for help on an alias.
  • You can optionally use a different description for a parameter in the Inputs section as you have for the Parameter section.
  • Web links are automatically rendered in markdown format, for possible post-processing to live links. (This enhancement is pending.)

I liked this open-source utility so much I started contributing to it, providing several of the above benefits. And I wrote a comprehensive guide to using it, entitled Documenting Your PowerShell Binary Cmdlets, just published on Simple-Talk.com.

Upvotes: 1

Anon
Anon

Reputation: 7184

In terms of graphical tools for editing XML PowerShell help (PSMAML) you can use:

Upvotes: 0

Roman Kuzmin
Roman Kuzmin

Reputation: 42073

I had to document my module and did not find any better solution than to create 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.

Here is the template of help data for commands (cmdlet, functions, scripts) and providers:

### Command help data

@{
    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 = '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 = '...'
        }
        #...
    )
}

Upvotes: 1

Glenn
Glenn

Reputation: 1855

I've been looking at a way to embed the documentation in the snapin/module C# code and PoshBuild is starting to look like my best option. It doesn't provide a way to include some of the documentation elements (e.g., synopsis and examples), but it's still a good option.

Upvotes: 0

Chad Miller
Chad Miller

Reputation: 41847

I've created a Powershell script that will generate MAML for cmdlets and functions regardless of whether they part of modules. It's not perfect as the generated MAML will require some manual editing, but so does the cmdlet help editor you referenced. I have a blog post about it here

If you use it and find corrections feel free to update the script on PoshCode.

Upvotes: 4

Related Questions