Udostępnij za pomocą

Utwórz nowe polecenie pomocy Markdown przy użyciu Microsoft.PowerShell.PlatyPS

Zamiast ręcznego pisania plików pomocy MAML moduł Microsoft.PowerShell.PlatyPS (PlatyPS) umożliwia tworzenie dokumentacji poleceń w formacie Markdown, a następnie konwertowanie plików Markdown na format MAML. PlatyPS tworzy szablon Markdown dla każdego polecenia w module. PlatyPS nie pisze za Ciebie treści pomocy. Szablon należy wypełnić zawartością opisującą polecenia, parametry, przykłady i inne informacje pomocnicze.

Tworzenie zawartości pomocy MAML składa się z następujących kroków:

  1. Utwórz pliki szablonów języka Markdown dla modułu.
  2. Edytuj pliki Markdown, aby dodać zawartość.
  3. Przetestuj pliki Markdown, aby upewnić się, że struktura jest poprawna.
  4. Konwertowanie plików Markdown na format MAML i publikowanie pomocy

W tym artykule opisano pierwsze trzy kroki.

Wymagania wstępne

Przed rozpoczęciem należy zainstalować moduł Microsoft.PowerShell.PlatyPS z Galeria programu PowerShell. Musisz również mieć zainstalowany moduł, który chcesz udokumentować.

Użyj następującego polecenia, aby zainstalować PlatyPS:

Install-PSResource -Name Microsoft.PowerShell.PlatyPS

Krok 1 — Utwórz pliki szablonów Markdown

Istnieją dwa typy plików Markdown do utworzenia dla modułu:

  • Pliki pomocy poleceń — po jednym pliku dla każdego polecenia.
  • Plik modułu — zawiera metadane dotyczące modułu i wyświetla listę poleceń w module.

Oba typy plików są wymagane, jeśli chcesz utworzyć zawartość MAML dla swojego modułu.

Uruchom następujące polecenie, aby utworzyć pliki Markdown:

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

Polecenie New-MarkdownCommandHelp tworzy folder o nazwie ./docs/YourModuleName w bieżącym katalogu. Folder zawiera pliki Markdown dla każdego polecenia w module, a także plik modułu o nazwie YourModuleName.md. Plik modułu zawiera metadane dotyczące modułu i zawiera listę wszystkich poleceń wraz z opisem streszczenia. Plik ten można przekonwertować do formatu HTML, który będzie używany jako strona indeksowa modułu w witrynie internetowej dokumentacji.

Gdy plik modułu jest tworzony po raz pierwszy, nie ma opisów streszczeń poleceń. Pliki Markdown zawierają symbole zastępcze, które należy zastąpić opisami streszczenia.

Jeśli parametr WithModulePage zostanie pominięty, plik modułu nie zostanie utworzony. Plik modułu można utworzyć później, po napisaniu opisów streszczenia, uruchamiając New-MarkdownModuleFile polecenie. Przykład:

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

To polecenie tworzy plik modułu w folderze ./docs/YourModuleName . Parametr -Force zastępuje wszystkie istniejące pliki modułów. Jeśli opisy streszczeń zostały wypełnione w plikach poleceń, opisy są zawarte w pliku modułu.

Aby uzyskać więcej informacji na temat tych poleceń, zobacz następujące artykuły:

Dalsze kroki

  • Last updated on