Generador de ayuda de PowerShell MAML

Question

¿Alguien sabe de una utilidad para generar archivos de ayuda de 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 si forman parte de los módulos. No es perfecto ya que el MAML generado requerirá alguna edición manual, pero también lo hace el editor de ayuda de cmdlet al que se hace referencia. Tengo una publicación en el blog al respecto here

Si la usa y encuentra las correcciones, no dude en actualizar the script on PoshCode.

Answer 2

Tuve que documentar mi módulo y no encontré ninguna solución mejor que crear mi propio generador de ayuda MAML. Aquí está: https://github.com/nightroman/Helps

El módulo crea archivos de ayuda de PowerShell MAML desde los scripts de ayuda de PowerShell. Los scripts de ayuda son casi WYSIWYG, se parecen mucho a la ayuda resultante. Aún así, solo son scripts y esto hace que muchas funciones útiles sean fáciles. Uno de ellos es crear archivos de ayuda para varias culturas.

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

### 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

que he estado buscando en una manera de integrar la documentación en el módulo/código de complemento C# y PoshBuild está empezando a verse como mi mejor opción. No proporciona una forma de incluir algunos de los elementos de la 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 ayuda PowerShell (PSMAML) que puede utilizar:

• PowerShell Cmdlet Help 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 sus binario cmdlets de PowerShell (es decir, los que están escritos en C#) al igual que cualquier otro # librerías de C, y al igual que con guión cmdlets (las escritas en PowerShell): use comentarios de documentación en línea.

¡Ya no es necesario mantener un archivo paralelo MAML a mano! Simplemente instrumente su compilación para que cuando recompile su proyecto C# ejecute el generador de documentación y obtendrá un módulo . dll y un módulo . dll-Help.xml. Este último es utilizado directamente por PowerShell para proporcionar ayuda en sus cmdlets cuando invoca Get-Help.

Y XmlDoc2CmdletDoc incluso ofrece un conmutador -strict para asegurarse de que ha documentado exhaustivamente sus cmdlets; si usas el interruptor y te perdiste algo, tu compilación fallará, como debería.

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

• Cada tipo de encargo en los Salidas sección incluye una descripción.
• La sección de sintaxis incluye posibles valores para los tipos enumerados.
• La sección El parámetro incluye valores posibles para los tipos enumerados.
• Los alias se documentan automáticamente en la sección de Parámetros.
• Los alias se tratan como parámetros de primera clase, por lo que puede solicitar ayuda sobre un alias.
• Opcionalmente, puede utilizar una descripción diferente para un parámetro en la sección Entradas , como lo hizo para la sección Parámetro.
• Los enlaces web se procesan automáticamente en formato de rebajas, para posprocesar los enlaces en vivo. (Esta mejora está pendiente.)

Me gustó tanto esta utilidad de código abierto que comencé a contribuir a ella, proporcionando varios de los beneficios anteriores. Y escribí una guía completa para usarla, titulada Documenting Your PowerShell Binary Cmdlets, recién publicada en Simple-Talk.com.