PowerShell maml ajuda gerador

Question

Alguém conhece uma utilidade para gerar arquivos de ajuda do PowerShell CMDLET? Fazer isso à mão parece um pouco tedioso ...

Eu localizei: http://blogs.msdn.com/powershell/archive/2007/09/01/new-and-improted-cmdlet-help-editor-tool.aspx

Alguma versões atualizadas? Não posso selecionar um módulo. Eu tenho um módulo binário.

Answer 1

Criei um script do PowerShell que gerará MAML para cmdlets e funções, independentemente de eles parte de módulos. Não é perfeito, pois o MAML gerado exigirá alguma edição manual, mas o editor de ajuda do CMDLET que você referenciou. Eu tenho um post sobre isso aqui

Se você o usar e encontrar correções, fique à vontade para atualizar o script no picahcode.

Answer 2

Eu tive que documentar meu módulo e não encontrei nenhuma solução melhor do que criar meu próprio MAML Help Builder. Aqui está:https://github.com/nightroman/helps

O módulo constrói os arquivos de ajuda do PowerShell maml a partir de scripts do PowerShell. Os scripts de ajuda são quase wysiwyg, eles parecem muito semelhantes à ajuda do resultado. Ainda assim, eles são apenas scripts e isso facilita muitos recursos úteis. Um deles é criar arquivos de ajuda para várias culturas.

Aqui está o modelo de dados de ajuda para comandos (cmdlet, funções, scripts) e provedores:

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

Eu tenho procurado uma maneira de incorporar a documentação no código Snapin/Module C# e Poshbuild está começando a parecer minha melhor opção. Ele não fornece uma maneira de incluir alguns dos elementos de documentação (por exemplo, sinopse e exemplos), mas ainda é uma boa opção.

Answer 4

Em termos de ferramentas gráficas para editar ajuda XML PowerShell (PSMAML) que você pode usar:

• Editor de ajuda do PowerShell CMDlet (Open Source, algo de sucessor espiritual do editor de ajuda do CMDLET).
• PowerShell Helpwriter (Comercial).

Answer 5

Com o advento da fonte aberta Xmldoc2cmdletdoc, agora você pode documentar seu binário PowerShell cmdlets (ou seja, aqueles escritos em C#) como qualquer outra biblioteca C# script cmdlets (aqueles escritos no PowerShell): use comentários em linha em linha.

Você não precisa mais manter um paralelo Maml Arquivo à mão! Basta instrumentar sua construção para que, quando você recompile seu projeto C#, ele executa o gerador de documentação e você obtém ambos módulo.dll e a módulo.dll-help.xml. Este último é usado diretamente pelo PowerShell para fornecer ajuda em seus cmdlets quando você invoca Get-Help.

E xmldoc2cmdletdoc até oferece um -strict Mudar para garantir que você documentou de forma abrangente seus cmdlets; Se você usar o comutador e perdeu alguma coisa, sua construção falhará, como deveria.

Outros benefícios fornecidos automaticamente por xmldoc2cmdletdoc ("seções" nesta lista refere -se às seções de ajuda apresentada por Get-Help):

• Cada tipo personalizado no Saídas A seção inclui uma descrição.
• o Sintaxe A seção inclui possíveis valores para tipos enumerados.
• o Parâmetro A seção inclui possíveis valores para tipos enumerados.
• Aliases são documentados automaticamente no Parâmetros seção.
• Os aliases são tratados como parâmetros de primeira classe para que você possa pedir ajuda em um alias.
• Você pode opcionalmente usar uma descrição diferente para um parâmetro no Entradas seção como você tem para o Parâmetro seção.
• Os links da Web são renderizados automaticamente no formato de marcação, para possível pós-processamento para links ao vivo. (Este aprimoramento está pendente.)

Gostei tanto dessa utilitária de código aberto que comecei a contribuir para ele, fornecendo vários dos benefícios acima. E escrevi um guia abrangente para usá -lo, intitulado Documentando seus cmdlets binários do PowerShell, acabei de publicar no Simple-Talk.com.