Dela via

Skapa ett nytt kommando hjälp Markdown med hjälp av Microsoft.PowerShell.PlatyPS

I stället för att skriva MAML-hjälpfiler för hand kan du med modulen Microsoft.PowerShell.PlatyPS (PlatyPS) skapa kommandodokumentation i Markdown-format och sedan konvertera Markdown-filerna till MAML-format. PlatyPS skapar en Markdown-mall för varje kommando i modulen. PlatyPS skriver inte hjälpinnehållet åt dig. Du måste fylla i mallen med innehåll som beskriver kommandon, parametrar, exempel och annan stödinformation.

Att skapa MAML-hjälpinnehåll består av följande steg:

  1. Skapa Markdown-mallfilerna för modulen.
  2. Redigera Markdown-filerna för att lägga till innehåll.
  3. Testa Markdown-filerna för att se till att strukturen är korrekt.
  4. Konvertera Markdown-filerna till MAML-format och publiceringshjälp

I den här artikeln beskrivs de tre första stegen.

Förutsättningar

Innan du börjar måste du installera modulen Microsoft.PowerShell.PlatyPS från PowerShell-galleriet. Du måste också ha installerat den modul som du vill dokumentera.

Använd följande kommando för att installera PlatyPS:

Install-PSResource -Name Microsoft.PowerShell.PlatyPS

Steg 1 – Skapa Markdown-mallfilerna

Det finns två typer av Markdown-filer att skapa för modulen:

  • Kommandohjälpfiler – en fil för varje kommando.
  • Modulfil - innehåller metadata om modulen och listar kommandona i modulen.

Båda filtyperna krävs om du vill skapa MAML-innehåll för modulen.

Kör följande kommando för att skapa Markdown-filerna:

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

Kommandot New-MarkdownCommandHelp skapar en mapp med namnet ./docs/YourModuleName i den aktuella katalogen. Mappen innehåller Markdown-filerna för varje kommando i modulen, samt en modulfil med namnet YourModuleName.md. Modulfilen innehåller metadata om modulen och listar varje kommando med dess synopsisbeskrivning. Den här filen kan konverteras till HTML för att användas som en indexsida för modulen på en dokumentationswebbplats.

När modulfilen först skapas finns det inga synopsisbeskrivningar för kommandona. Markdown-filerna innehåller platshållare som du måste ersätta med synopsisbeskrivningarna.

Om du utelämnar parametern WithModulePage skapas inte modulfilen. Du kan skapa modulfilen senare, när du har skrivit synopsisbeskrivningarna, genom att köra kommandot New-MarkdownModuleFile . Till exempel:

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

Det här kommandot skapar modulfilen i mappen ./docs/YourModuleName . Parametern -Force skriver över alla befintliga modulfiler. Om du har fyllt i synopsisbeskrivningarna i kommandofilerna ingår beskrivningarna i modulfilen.

Mer information om dessa kommandon finns i följande artiklar:

Nästa steg