Создание новой команды help Markdown с помощью Microsoft.PowerShell.PlatyPS

Вместо того, чтобы писать файлы справки MAML от руки, модуль Microsoft.PowerShell.PlatyPS (PlatyPS) позволяет создавать документацию по командам в формате Markdown, а затем преобразовывать файлы Markdown в формат MAML. PlatyPS создает шаблон Markdown для каждой команды в вашем модуле. PlatyPS не пишет содержимое справки за вас. Вы должны заполнить шаблон содержимым, которое описывает команды, параметры, примеры и другую вспомогательную информацию.

Создание содержимого справки MAML состоит из следующих этапов:

  1. Создайте файлы шаблона Markdown для своего модуля.
  2. Отредактируйте файлы Markdown, чтобы добавить содержимое.
  3. Проверьте файлы Markdown, чтобы убедиться в правильности структуры.
  4. Преобразование файлов Markdown в формат MAML и публикация справки

В этой статье описаны первые три шага.

Предпосылки

Прежде чем начать, необходимо установить модуль Microsoft.PowerShell.PlatyPS из коллекции PowerShell. Кроме того, у вас должен быть установлен модуль, который вы хотите задокументировать.

Используйте следующую команду для установки PlatyPS:

Install-PSResource -Name Microsoft.PowerShell.PlatyPS

Шаг 1 - Создание файлов шаблона Markdown

Существует два типа файлов Markdown, которые можно создать для модуля:

  • Файлы справки по командам - по одному файлу для каждой команды.
  • Файл модуля - содержит метаданные о модуле и перечисляет команды в модуле.

Оба типа файлов необходимы, если вы хотите создать содержимое MAML для своего модуля.

Выполните следующую команду для создания файлов Markdown:

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

Команда New-MarkdownCommandHelp создает папку с именем ./docs/YourModuleName в текущем каталоге. Папка содержит файлы Markdown для каждой команды в модуле, а также файл модуля с именем YourModuleName.md. Файл модуля содержит метаданные о модуле и перечисляет каждую команду с описанием ее краткого обзора. Этот файл может быть преобразован в HTML для использования в качестве индексной страницы для модуля на веб-сайте документации.

Когда файл модуля создается впервые, у него нет кратких описаний команд. Файлы Markdown содержат заполнители, которые необходимо заменить описаниями синопсиса.

Если опустить параметр WithModulePage , файл модуля не будет создан. Вы можете создать файл модуля позже, после того, как напишете описание синопсиса, выполнив New-MarkdownModuleFile команду. Рассмотрим пример.

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

Эта команда создает файл модуля в ./docs/YourModuleName папке. Этот -Force параметр перезаписывает любой существующий файл модуля. Если вы заполнили описания синопсиса в командных файлах, то описания будут включены в файл модуля.

Дополнительные сведения об этих командах см. в следующих статьях:

Дальнейшие шаги

  • Last updated on