Dela via

Uppdatera Markdown-hjälpfiler med hjälp av Microsoft.PowerShell.PlatyPS

Under livscykeln för en PowerShell-modul kan du lägga till nya kommandon och parametrar eller ändra befintliga parametrar. När du släpper en ny version av modulen bör du uppdatera Markdown-hjälpfilerna för modulen för att säkerställa att hjälpinnehållet är korrekt och fullständigt.

Kommandona Update-MarkdownCommandHelp och Update-MarkdownModuleFile uppdaterar Markdown-filerna så att de återspeglar ändringar i modulen. Om du vill uppdatera innehållet måste du först importera den uppdaterade modulen till den aktuella sessionen. Uppdateringskommandona importerar de befintliga Markdown-filerna och uppdaterar innehållet baserat på modulen som lästs in i den aktuella sessionen. Kommandona skapar säkerhetskopior av befintligt innehåll innan ändringar görs. Du kan jämföra de uppdaterade filerna med säkerhetskopiorna för att se vad som har ändrats.

Du kan använda uppdateringskommandona för att konvertera äldre Markdown-filer till PlatyPS-formatet. Kommandona kan importera Markdown-filer som skapats av den tidigare versionen av PlatyPS (platyPS v0.14.2). Formatet för uppdateringsinnehållet skrivs dock med hjälp av PlatyPS Markdown-formatet.

Uppdatera kommandot Markdown-filer

Update-MarkdownCommandHelp Använd kommandot för att uppdatera kommandot Markdown-filer. Till exempel:

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

Du måste granska varje uppdaterad fil för att säkerställa att innehållet är korrekt och fullständigt. Om du konverterar äldre Markdown-filer till PlatyPS-formatet finns det ett nytt ## ALIASES avsnitt som du måste redigera. Det här avsnittet används för att dokumentera alla alias som har definierats för kommandot. Det här avsnittet är valfritt och kan tas bort om det inte finns några alias. Du måste också lägga till nya exempel och dokumentera eventuella nya parametrar.

Uppdatera Markdown-filen för modulen

När du är klar med redigeringen och testningen av kommandot Markdown-filer kan du uppdatera Markdown-filen för modulen med hjälp av Update-MarkdownModuleFile kommandot. Till exempel:

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

Se till att granska den uppdaterade modulfilen för att säkerställa att innehållet är korrekt och fullständigt.

Jämföra ändringarna med säkerhetskopiorna

Kommandot Update-MarkdownCommandHelp lägger till ny information i de befintliga Markdown-kommandofilerna, men är försiktig när det gäller att ändra befintligt innehåll. All ny information som läggs till i Markdown innehåller platshållarsträngar som du måste ersätta med korrekt information. Det finns också objekt i hjälpfilerna som inte kan uppdateras korrekt. Till exempel:

  • PlatyPS-kommandon hämtar information om utdatatyp genom att inspektera kommandot med hjälp av Get-Command. Men om kommandoförfattaren inte definierade utdatatyper är informationen om utdatatypen ofullständig. Du kan lägga till information om utdatatyp i Markdown-filen. Update-MarkdownCommandHelp lägger bara till information om utdatatyp som den kan verifiera, men den tar inte bort någon befintlig information om utdatatyp.

  • På samma sätt kan du använda uttryck med jokertecken med vissa parametrar. Om kommandoförfattaren har lagt till attributet [SupportsWildcards()] i parametern återspeglas den informationen korrekt i markdown-filen. Det är dock mycket vanligt att kommandoförfattare utelämnar attributet. Du kan ändra parameterinformationen i Markdown-filen för att ange att jokertecken stöds. Du måste se till att den uppdaterade informationen är korrekt.

För bästa resultat, använd ett filjämförelseverktyg för att jämföra de uppdaterade filerna med säkerhetskopiorna. Du kan göra jämförelser sida vid sida med hjälp av Visual Studio Code eller ett jämförelseverktyg som Beyond Compare.

När du har slutfört uppdateringarna kan du ta bort säkerhetskopiorna.

Nästa steg

I följande artikel beskrivs strukturen för Markdown-filerna och hur du ser till att innehållet följer det förväntade formatet.