Powershell documentation whith Markdown

O Powershell possui uma estrutura de documentação bem definida. Utilizando o comando Get-Help, você consegue ver a documentação de qualquer comando Powershell. Até mesmo informação de comandos que não foram explicitamente detalhados são obtidas, inferindo a estrutura do script, commandlet, função, etc.

Este artigo descreve como escrever a documentação de Powershell para ser utilizada com o comando Get-Help.

Exitem "basicamente" duas abordagens:

  • Help baseado em comentários de funções e scripts;
  • Help baseado em um arquivo externo, que possuim um schema específico de xml chamado MAML;

Ambas tem suas aplicações, mas é comum na criação de módulos muito grandes ou commandlets, a utilização de Helps baseados em arquivos MAML.

O MAML é um arquivo xml que possui uma estrutura bem definida, mas que é ruim para ser editado sem a ajuda de ferramentas. Existem algumas ferramentas, como a Powershell Cmdlet Help Editor que tornam essa tarefa muito fácil.

Porém, é mais uma ferramenta para se incorporar no desenvolvimento com Powershell, e utiliza uma interface não muito produtiva. Documentação é texto, e é mais natural e produtivo editá-la como um arquivo de texto do que ficar selecionando e preenchendo campos.

No vídeo a seguir, mostro como utilizar o PlatyPS (ferramenta criada pelo time do Powershell) para gerar e editar documentação de Powershell (scripts/módulos/commandlets) utilizando Markdown.

A idéia é tornar o processo de documentação de Powershell mais produtivo, eliminar uma ferramenta e, de quebra, ter um documento que é facilmente renderizado em HTML.

Espero que gostem. Assitam e deixem seus comentários.