Partilhar via

Atualizar arquivos de ajuda do Markdown usando Microsoft.PowerShell.PlatyPS

Durante o ciclo de vida de um módulo do PowerShell, você pode adicionar novos comandos e parâmetros ou alterar parâmetros existentes. Ao lançar uma nova versão do módulo, você deve atualizar os arquivos de ajuda Markdown para o módulo para garantir que o conteúdo da ajuda seja preciso e completo.

Os Update-MarkdownCommandHelp comandos e Update-MarkdownModuleFile atualizam os arquivos Markdown para refletir as alterações no módulo. Para atualizar o conteúdo, você deve primeiro importar o módulo atualizado para a sessão atual. Os comandos update importam os arquivos Markdown existentes e atualizam o conteúdo com base no módulo carregado na sessão atual. Os comandos criam backups do conteúdo existente antes de fazer alterações. Você pode comparar os arquivos atualizados com os arquivos de backup para ver o que mudou.

Você pode usar os comandos update para converter arquivos Markdown mais antigos para o formato PlatyPS. Os comandos podem importar arquivos Markdown criados pela versão anterior do PlatyPS (platyPS v0.14.2). No entanto, o formato do conteúdo da atualização é escrito usando o formato PlatyPS Markdown.

Atualizar o comando Markdown arquivos

Use o Update-MarkdownCommandHelp comando para atualizar os arquivos Markdown do comando. Por exemplo:

Import-Module -Name 'YourModuleName' -Force # Load the updated module
Measure-PlatyPSMarkdown -Path ./docs/YourModuleName/*.md
    Where-Object Filetype -match 'CommandHelp' |
    Update-MarkdownCommandHelp -Path {$_.FilePath}

Você deve inspecionar cada arquivo atualizado para garantir que o conteúdo esteja correto e completo. Se você estiver convertendo arquivos Markdown mais antigos para o formato PlatyPS, há uma nova ## ALIASES seção que você deve editar. Esta seção é usada para documentar quaisquer aliases definidos para o comando. Esta seção é opcional e pode ser removida se não houver aliases. Você também precisa adicionar novos exemplos e documentar quaisquer novos parâmetros.

Atualizar o arquivo Markdown do módulo

Depois de concluir a edição e o teste dos arquivos Markdown comando, você pode atualizar o arquivo Markdown do módulo usando o Update-MarkdownModuleFile comando. Por exemplo:

Measure-PlatyPSMarkdown -Path ./docs/YourModuleName/*.md |
    Where-Object Filetype -match 'CommandHelp' |
    Import-MarkdownCommandHelp -Path {$_.FilePath} |
    Update-MarkdownModuleFile -Path ./docs/YourModuleName/YourModuleName.md

Certifique-se de inspecionar o arquivo de módulo atualizado para garantir que o conteúdo esteja correto e completo.

Comparando as alterações com os arquivos de backup

O Update-MarkdownCommandHelp comando adiciona novas informações aos arquivos de Markdown de comando existentes, mas é conservador quanto à alteração do conteúdo existente. Qualquer nova informação adicionada ao Markdown contém cadeias de caracteres de espaço reservado que você deve substituir por informações precisas. Além disso, há itens nos arquivos de ajuda que não podem ser atualizados com precisão. Por exemplo:

  • Os comandos PlatyPS obtêm informações de tipo de saída inspecionando o comando usando Get-Command. No entanto, se o autor do comando não definiu os tipos de saída, as informações do tipo de saída estarão incompletas. Você pode adicionar informações de tipo de saída no arquivo Markdown. Update-MarkdownCommandHelp apenas adiciona informações de tipo de saída que pode verificar, mas não remove nenhuma informação de tipo de saída existente.

  • Da mesma forma, alguns parâmetros permitem que você use expressões curinga. Se o autor do comando adicionou o [SupportsWildcards()] atributo ao parâmetro, essa informação será refletida corretamente no arquivo de markdown. No entanto, é muito comum que os autores de comandos omitam o atributo. Você pode alterar as informações de parâmetro no arquivo Markdown para indicar que há suporte para curingas. Você precisa garantir que as informações atualizadas estejam corretas.

Para obter melhores resultados, use uma ferramenta de comparação de arquivos para comparar os arquivos atualizados com os arquivos de backup. Você pode fazer comparações lado a lado usando o Visual Studio Code ou uma ferramenta de comparação como Beyond Compare.

Depois de concluir as atualizações, você pode excluir os arquivos de backup.

Próximos passos

O artigo a seguir descreve a estrutura dos arquivos Markdown e como garantir que o conteúdo siga o formato esperado.

  • Last updated on