PowerShell Generador de Ayuda MAML

Question

¿Alguien sabe de una utilidad para generar archivos de ayuda cmdlet de PowerShell? Hacerlo a mano parece un poco tedioso ...

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

cualquier versión actualizada? No puedo seleccionar un módulo. Tengo un módulo binario.

Answer 1

He creado un script de PowerShell que generará MAML para cmdlets y funciones independientemente de que parte de los módulos. No es perfecto como el MAML generada requerirá un poco de edición manual, pero también lo hace el editor de cmdlet ayuda que se hace referencia. Tengo un blog al respecto aquí

Si lo usa y encontrar correcciones se sienten libres para actualizar el script en PoshCode .

Answer 2

he tenido que documentar mi módulo y no encontrar ninguna solución mejor que crear mi propio MAML ayuda constructor. Aquí está: https://github.com/nightroman/Helps

El módulo se basa archivos de ayuda PowerShell maml desde scripts de ayuda PowerShell. Ayuda guiones son casi WYSIWYG, tienen un aspecto muy similar a la ayuda resultado. Aún así, son sólo los scripts y esto hace que una gran cantidad de características útiles fácil. Uno de ellos es la creación de archivos de ayuda para varios cultivos.

Esta es la plantilla de datos de ayuda para los comandos (cmdlet, funciones, scripts) y los proveedores de:

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

Answer 3

He estado buscando en una manera de integrar la documentación en el módulo de código C complemento / # y PoshBuild está empezando a parecerse a mi mejor opción. No proporciona una manera de incluir algunos de los elementos de documentación (por ejemplo, sinopsis y ejemplos), pero sigue siendo una buena opción.

Answer 4

En cuanto a las herramientas gráficas para la edición de XML PowerShell ayuda (PSMAML) que puede utilizar:

• PowerShell cmdlet Ayuda Editor (Open Source, algo así como un sucesor espiritual de Ayuda de cmdlet Editor).
• PowerShell HelpWriter (Comercial).

Answer 5

Con el advenimiento de la fuente abierta XmlDoc2CmdletDoc , ahora se puede documentar su binaria cmdlets de PowerShell (es decir, los que están escritos en C #) al igual que cualquier otra biblioteca de C #, y al igual que índice (cmdlets de los escritos en PowerShell): utilización de documentación en línea comentarios.

Ya no es necesario mantener un paralelismo MAML archivo a mano! instrumento sólo su estructura de manera que cuando vuelva a compilar el proyecto de C # que ejecuta el generador de documentación y se obtiene tanto un Módulo . DLL y Módulo . DLL-help.xml . El último se utiliza directamente por PowerShell para proporcionar ayuda en sus cmdlets cuando se invoca Get-Help.

Y XmlDoc2CmdletDoc incluso ofrece un interruptor -strict para asegurarse de que ha documentado exhaustivamente sus cmdlets; si se utiliza el interruptor y se ha perdido algo, su construcción fallará, como debe ser.

Otros beneficios proporcionados automáticamente por XmlDoc2CmdletDoc ( "secciones" en esta lista se refiere a las secciones de ayuda presentados por Get-Help):

• Cada tipo personalizado en el Salidas sección incluye una descripción.
• La Sintaxis sección incluye valores posibles para los tipos enumerados.
• La Parámetro sección incluye valores posibles para los tipos enumerados.
• Los alias se documentan automáticamente en la sección Parámetros .
• Los alias se tratan como parámetros de primer nivel para que pueda pedir ayuda en un alias.
• Se puede usar opcionalmente una descripción diferente para un parámetro en las entradas de la sección que tiene para el Parámetros .
• Los enlaces web se procesan automáticamente en formato de rebajas, para su posible post-procesamiento de los enlaces en vivo. (Esta mejora está pendiente.)

Me gusta esta utilidad de código abierto tanto que empecé a contribuir a ella, proporcionando varios de los beneficios anteriores. Y escribí una guía completa de usarlo, titulado Documentación del binario PowerShell cmdlets , que acaba de publicar en Simple-Talk.com.