Partilhar via

Criar novo comando ajuda Markdown usando Microsoft.PowerShell.PlatyPS

Em vez de escrever manualmente arquivos de ajuda MAML, o módulo Microsoft.PowerShell.PlatyPS (PlatyPS) permite criar documentação de comando no formato Markdown e, em seguida, converter os arquivos Markdown para o formato MAML. PlatyPS cria um modelo de Markdown para cada comando no seu módulo. PlatyPS não escreve o conteúdo de ajuda para você. Você deve preencher o modelo com conteúdo que descreva os comandos, parâmetros, exemplos e outras informações de suporte.

A criação de conteúdo de ajuda MAML consiste nas seguintes etapas:

  1. Crie os arquivos de modelo Markdown para seu módulo.
  2. Edite os arquivos Markdown para adicionar conteúdo.
  3. Teste os arquivos Markdown para garantir que a estrutura esteja correta.
  4. Converta os arquivos Markdown para o formato MAML e publique a ajuda

Este artigo descreve as três primeiras etapas.

Pré-requisitos

Antes de começar, você deve instalar o módulo Microsoft.PowerShell.PlatyPS da Galeria do PowerShell. Você também deve ter instalado o módulo que deseja documentar.

Use o seguinte comando para instalar o PlatyPS:

Install-PSResource -Name Microsoft.PowerShell.PlatyPS

Etapa 1 - Criar os arquivos de modelo Markdown

Há dois tipos de arquivos Markdown para criar para o seu módulo:

  • Command help files - um arquivo para cada comando.
  • Arquivo do módulo - contém metadados sobre o módulo e lista os comandos no módulo.

Ambos os tipos de arquivo são necessários se você quiser criar conteúdo MAML para seu módulo.

Execute o seguinte comando para criar os arquivos Markdown:

$newMarkdownCommandHelpSplat = @{
    ModuleInfo = Get-Module -Name 'YourModuleName'
    OutputFolder = './docs'
    WithModulePage = $true
}
New-MarkdownCommandHelp @newMarkdownCommandHelpSplat

O New-MarkdownCommandHelp comando cria uma pasta nomeada ./docs/YourModuleName no diretório atual. A pasta contém os arquivos Markdown para cada comando no módulo, bem como um arquivo de módulo chamado YourModuleName.md. O arquivo de módulo contém metadados sobre o módulo e lista cada comando com sua descrição de sinopse. Este arquivo pode ser convertido em HTML para ser usado como uma página de índice para o módulo em um site de documentação.

Quando o arquivo de módulo é criado pela primeira vez, não há descrições de sinopse para os comandos. Os arquivos Markdown contêm espaços reservados que você deve substituir pelas descrições de sinopse.

Se você omitir o parâmetro WithModulePage , o arquivo de módulo não será criado. Você pode criar o arquivo de módulo mais tarde, depois de ter escrito as descrições da sinopse, executando o New-MarkdownModuleFile comando. Por exemplo:

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

Este comando cria o arquivo de módulo na ./docs/YourModuleName pasta. O -Force parâmetro substitui qualquer arquivo de módulo existente. Se você tiver preenchido as descrições de sinopse nos arquivos de comando, as descrições serão incluídas no arquivo de módulo.

Para obter mais informações sobre esses comandos, consulte os seguintes artigos:

Próximos passos

  • Last updated on