Delen via

Maak een nieuwe opdracht Help Markdown met behulp van Microsoft.PowerShell.PlatyPS

In plaats van MAML-helpbestanden met de hand te schrijven, kunt u met de module Microsoft.PowerShell.PlatyPS (PlatyPS) opdrachtdocumentatie maken in Markdown-indeling en vervolgens de Markdown-bestanden converteren naar MAML-indeling. PlatyPS maakt een Markdown-sjabloon voor elk commando in uw module. PlatyPS schrijft de helpinhoud niet voor u. U moet de sjabloon invullen met inhoud die de opdrachten, parameters, voorbeelden en andere ondersteunende informatie beschrijft.

Het maken van MAML-helpinhoud bestaat uit de volgende stappen:

  1. Maak de Markdown-sjabloonbestanden voor uw module.
  2. Bewerk de Markdown-bestanden om inhoud toe te voegen.
  3. Test de Markdown-bestanden om er zeker van te zijn dat de structuur correct is.
  4. Converteer de Markdown-bestanden naar MAML-indeling en help bij het publiceren

In dit artikel worden de eerste drie stappen beschreven.

Vereiste voorwaarden

Voordat u begint, moet u de module Microsoft.PowerShell.PlatyPS installeren vanuit de PowerShell-galerie. U moet ook de module hebben geïnstalleerd die u wilt documenteren.

Gebruik het volgende commando om PlatyPS te installeren:

Install-PSResource -Name Microsoft.PowerShell.PlatyPS

Stap 1 - Maak de Markdown-sjabloonbestanden

Er zijn twee soorten Markdown-bestanden die u voor uw module kunt maken:

  • Helpbestanden voor opdrachten - één bestand voor elke opdracht.
  • Modulebestand - bevat metagegevens over de module en geeft een overzicht van de opdrachten in de module.

Beide bestandstypen zijn vereist als u MAML-inhoud voor uw module wilt maken.

Voer de volgende opdracht uit om de Markdown-bestanden te maken:

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

Met de New-MarkdownCommandHelp opdracht wordt een map gemaakt met de naam ./docs/YourModuleName in de huidige map. De map bevat de Markdown-bestanden voor elke opdracht in de module, evenals een modulebestand met de naam YourModuleName.md. Het modulebestand bevat metagegevens over de module en geeft een overzicht van elke opdracht met de synopsisbeschrijving. Dit bestand kan worden geconverteerd naar HTML om te worden gebruikt als indexpagina voor de module op een documentatiewebsite.

Wanneer het modulebestand voor het eerst wordt gemaakt, zijn er geen synopsisbeschrijvingen voor de opdrachten. De Markdown-bestanden bevatten tijdelijke aanduidingen die u moet vervangen door de synopsisbeschrijvingen.

Als u de parameter WithModulePage weglaat, wordt het modulebestand niet gemaakt. U kunt het modulebestand later maken, nadat u de synopsisbeschrijvingen hebt geschreven, door de New-MarkdownModuleFile opdracht uit te voeren. Voorbeeld:

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

Met deze opdracht wordt het modulebestand in de ./docs/YourModuleName map gemaakt. De -Force parameter overschrijft elk bestaand modulebestand. Als je de synopsisbeschrijvingen in de opdrachtbestanden hebt ingevuld, worden de beschrijvingen opgenomen in het modulebestand.

Zie de volgende artikelen voor meer informatie over deze opdrachten:

Volgende stappen

  • Last updated on