Создание справки на основе XML с помощью PlatyPS

При создании модуля PowerShell всегда рекомендуется включить подробную справку по создаваемым командлетам. Если командлеты реализованы в скомпилированном коде, необходимо использовать справку на основе XML. Этот формат XML называется языком разметки microsoft assistance (MAML).

Устаревшая документация по пакету SDK PowerShell содержит сведения о создании справки по командлетам PowerShell, упакованным в модули. Однако PowerShell не предоставляет никаких средств для создания справки на основе XML. Документация по пакету SDK объясняет структуру справки MAML, но оставляет задачу создания сложного и глубоко вложенного содержимого MAML вручную.

В этом случае модуль PlatyPS может помочь.

Что такое PlatyPS?

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

PlatyPS создает заполнители для заполнения описаний и примеров. После добавления необходимых сведений PlatyPS компилирует файлы Markdown в файлы MAML. Система справки PowerShell также позволяет использовать файлы справки с открытым текстом (о разделах). PlatyPS имеет командлет для создания структурированного шаблона Markdown для нового о файле, но эти about_*.help.txt файлы должны храниться вручную.

Файлы справки MAML и Text можно включить в модуль. Вы также можете использовать PlatyPS для компиляции файлов справки в пакет CAB, который можно разместить для обновления справки.

Начало работы с PlatyPS

Сначала необходимо установить PlatyPS из коллекции PowerShell.

# Install using PowerShellGet 2.x
Install-Module platyps -Force

# Install using PSResourceGet 1.x
Install-PSResource platyps -Reinstall

После установки PlatyPS импортируйте модуль в сеанс.

Import-Module platyps

В следующей блок-схеме описывается процесс создания или обновления справочного содержимого PowerShell.

PlatyPS

Создание содержимого Markdown для модуля PowerShell

1. Импортируйте новый модуль в сеанс. Повторите этот шаг для каждого модуля, который необходимо задокументировать.

   Выполните следующую команду, чтобы импортировать модули:

   Import-Module <your module name>
   

2. Используйте PlatyPS для создания файлов Markdown для страницы модуля и всех связанных командлетов в модуле. Повторите этот шаг для каждого модуля, который необходимо задокументировать.

   $OutputFolder = <output path>
   $parameters = @{
       Module = <ModuleName>
       OutputFolder = $OutputFolder
       AlphabeticParamsOrder = $true
       WithModulePage = $true
       ExcludeDontShow = $true
       Encoding = [System.Text.Encoding]::UTF8
   }
   New-MarkdownHelp @parameters
   
   New-MarkdownAboutHelp -OutputFolder $OutputFolder -AboutName "topic_name"
   

   Если папка выходных данных не существует, New-MarkdownHelp создает ее. В этом примере New-MarkdownHelp создает файл Markdown для каждого командлета в модуле. Он также создает страницу модуля в файле с именем <ModuleName>.md. Эта страница модуля содержит список командлетов, содержащихся в модуле и заполнителях для описания Synopsis. Метаданные на странице модуля поступают из манифеста модуля и используются PlatyPS для создания XML-файла HelpInfo (как описано ниже).

   New-MarkdownAboutHelp создает новый о файле с именем about_topic_name.md.

   Дополнительные сведения см. в New-MarkdownHelp и New-MarkdownAboutHelp.

Обновление существующего содержимого Markdown при изменении модуля

PlatyPS также может обновлять существующие файлы Markdown для модуля. Используйте этот шаг для обновления существующих модулей с новыми командлетами, новыми параметрами или параметрами, которые изменились.

1. Импортируйте новый модуль в сеанс. Повторите этот шаг для каждого модуля, который необходимо задокументировать.

   Выполните следующую команду, чтобы импортировать модули:

   Import-Module <your module name>
   

2. Используйте PlatyPS для обновления файлов Markdown для целевой страницы модуля и всех связанных командлетов в модуле. Повторите этот шаг для каждого модуля, который необходимо задокументировать.

   $parameters = @{
       Path = <folder with Markdown>
       RefreshModulePage = $true
       AlphabeticParamsOrder = $true
       UpdateInputOutput = $true
       ExcludeDontShow = $true
       LogPath = <path to store log file>
       Encoding = [System.Text.Encoding]::UTF8
   }
   Update-MarkdownHelpModule @parameters
   

   Update-MarkdownHelpModule обновляет файлы командлета и модуля Markdown в указанной папке. Он не обновляет файлы about_*.md. Файл модуля (ModuleName.md) получает любой новый Synopsis текст, добавленный в файлы командлетов. Обновления файлов командлетов включают следующее изменение:

   • Новые наборы параметров
   • Новые параметры
   • Обновленные метаданные параметров
   • Обновленные сведения о входных и выходных типах

   Дополнительные сведения см. в разделе Update-MarkdownHelpModule.

Изменение новых или обновленных файлов Markdown

PlatyPS документирует синтаксис наборов параметров и отдельных параметров. Он не может создавать описания или предоставлять примеры. Конкретные области, в которых необходимо содержимое, содержатся в фигурных скобках. Например, {{ Fill in the Description }}

Необходимо добавить синопсис, описание командлета, описания для каждого параметра и по крайней мере один пример.

Подробные сведения о написании содержимого PowerShell см. в следующих статьях:

• руководство по стилю PowerShell
• справочные статьи по редактированию

После предоставления требуемого содержимого для каждого из командлетов необходимо убедиться, что вы обновляете целевую страницу модуля. Убедитесь, что модуль имеет правильные Module Guid и Download Help Link значения в метаданных YAML файла <module-name>.md. Добавьте отсутствующие метаданные.

Кроме того, вы можете заметить, что некоторые командлеты могут быть отсутствуют Synopsis (краткое описание). Следующая команда обновляет целевую страницу модуля с помощью текста описания Synopsis. Откройте целевую страницу модуля, чтобы проверить описание.

Update-MarkdownHelpModule -Path <full path output folder> -RefreshModulePage

Теперь, когда вы ввели все содержимое, можно создать файлы справки MAML, отображаемые Get-Help в консоли PowerShell.

Создание файлов внешней справки

На этом шаге создаются файлы справки MAML, отображаемые Get-Help в консоли PowerShell.

Чтобы создать файлы MAML, выполните следующую команду:

New-ExternalHelp -Path <folder with MDs> -OutputPath <output help folder>

New-ExternalHelp преобразует все файлы Markdown командлета в один (или несколько) MAML-файлов. Сведения о файлах преобразуются в обычные текстовые файлы со следующим форматом имен: about_topic_name.help.txt. Содержимое Markdown должно соответствовать требованию схемы PlatyPS. New-ExternalHelp завершает работу с ошибками, если содержимое не соответствует схеме. Чтобы устранить нарушения схемы, необходимо изменить файлы.

После завершения этого шага вы увидите *-help.xml и about_*.help.txt файлы в целевой выходной папке.

Дополнительные сведения см. в New-ExternalHelp

Тестирование скомпилированных файлов справки

Содержимое можно проверить с помощью командлета Get-HelpPreview :

Get-HelpPreview -Path "<ModuleName>-Help.xml"

Командлет считывает скомпилированный MAML-файл и выводит содержимое в том же формате, который будет получен из Get-Help. Это позволяет проверить результаты, чтобы убедиться, что файлы Markdown скомпилированы правильно и создают нужные результаты. При обнаружении ошибки повторно измените файлы Markdown и перекомпилируйте MAML.

Теперь вы готовы опубликовать файлы справки.

Публикация справки

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

• Упаковка файлов справки с помощью модуля
• Создание пакета справки с возможностью обновления, который пользователи устанавливают с помощью командлета Update-Help

Справка по упаковке модуля

Файлы справки можно упаковыть с помощью модуля. Дополнительные сведения о структуре папок см. в справке по написанию модулей. Список файлов справки следует включить в значение ключа FileList в манифест модуля.

Создание пакета справки с возможностью обновления

На высоком уровне действия по созданию обновляемой справки включают:

1. Поиск веб-сайта для размещения файлов справки
2. Добавление ключа HelpInfoURI в манифест модуля
3. Создание XML-файла HelpInfo
4. Создание CAB-файлов
5. Отправка файлов

Дополнительные сведения см. в статье Поддержка поддержки обновляемой справки: пошаговые.

PlatyPS помогает вам выполнить некоторые из этих действий.

HelpInfoURI — это URL-адрес, указывающий на расположение, в котором размещаются файлы справки в Интернете. Это значение настраивается в манифесте модуля. Update-Help считывает манифест модуля, чтобы получить этот URL-адрес и скачать обновляемое содержимое справки. Этот URL-адрес должен указывать только на расположение папки, а не на отдельные файлы. Update-Help создает имена файлов для скачивания на основе других сведений из манифеста модуля и XML-файла HelpInfo.

Командлет New-ExternalHelp создает XML-файл HelpInfo в выходной папке. XML-файл HelpInfo создается с помощью метаданных YAML, содержащихся в файлах Markdown модуля (ModuleName.md).

Командлет New-ExternalHelpCab создает ZIP-файлы и CAB-файлы, содержащие скомпилированные файлы MAML и about_*.help.txt. CAB-файлы совместимы со всеми версиями PowerShell. PowerShell 6 и выше может использовать ZIP-файлы.

$helpCabParameters = @{
    CabFilesFolder = $MamlOutputFolder
    LandingPagePath = $LandingPage
    OutputFolder = $CabOutputFolder
}
New-ExternalHelpCab @helpCabParameters

После создания ZIP-файлов и CAB-файлов отправьте ZIP-файлы, CAB и HelpInfo XML на HTTP-файловый сервер. Поместите файлы в расположение, указанное HelpInfoURI.

Дополнительные сведения см. в New-ExternalHelpCab.

Другие параметры публикации

Markdown — это универсальный формат, который легко преобразовать в другие форматы для публикации. Используя такие средства, как Pandoc, вы можете преобразовать файлы справки Markdown в различные форматы документов, включая обычный текст, HTML, PDF и форматы документов Office.

Кроме того, командлеты ConvertFrom-Markdown и Show-Markdown в PowerShell 6 и более поздних версиях можно использовать для преобразования Markdown в HTML или создания красочного дисплея в консоли PowerShell.

Известные проблемы

PlatyPS очень чувствительны к схеме для структуры файлов Markdown, которые он создает и компилирует. Очень легко написать допустимый Markdown, который нарушает эту схему. Дополнительные сведения см. в руководстве по стилю PowerShell и справочных статьях по редактированию.