Обновление файлов справки Markdown с помощью Microsoft.PowerShell.PlatyPS

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

Команды Update-MarkdownCommandHelp and Update-MarkdownModuleFile обновляют файлы Markdown в соответствии с изменениями в модуле. Чтобы обновить содержимое, необходимо сначала импортировать обновленный модуль в текущую сессию. Команды обновления импортируют существующие файлы Markdown и обновляют содержимое на основе модуля, загруженного в текущем сеансе. Команды создают резервные копии существующего содержимого перед внесением изменений. Вы можете сравнить обновленные файлы с файлами резервных копий, чтобы увидеть, что изменилось.

Вы можете использовать команды обновления для преобразования старых файлов Markdown в формат PlatyPS. Команды могут импортировать файлы Markdown, созданные предыдущей версией PlatyPS (platyPS v0.14.2). Однако формат содержимого обновления записывается с использованием формата PlatyPS Markdown.

Обновление команды Markdown files

Используйте команду Update-MarkdownCommandHelp для обновления команды Markdown files. Рассмотрим пример.

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

Необходимо проверить каждый обновленный файл, чтобы убедиться в правильности и полноте содержимого. Если вы конвертируете старые файлы Markdown в формат PlatyPS, необходимо отредактировать новый ## ALIASES раздел. Этот раздел используется для документирования всех псевдонимов, определенных для команды. Этот раздел является необязательным и может быть удален, если нет псевдонимов. Вам также нужно добавить все новые примеры и задокументировать любые новые параметры.

Обновите файл модуля Markdown

После того, как вы закончили редактирование и тестирование команды Markdown files, вы можете обновить файл модуля Markdown с помощью Update-MarkdownModuleFile команды. Рассмотрим пример.

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

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

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

Команда Update-MarkdownCommandHelp добавляет новые сведения в существующие файлы команды Markdown, но не обращает внимания на изменение существующего содержимого. Любая новая информация, добавляемая в Markdown, содержит строки-заполнители, которые необходимо заменить точной информацией. Кроме того, в файлах справки есть элементы, которые не могут быть обновлены точно. Рассмотрим пример.

• Команды PlatyPS получают информацию о типе вывода путем проверки команды с помощью .Get-Command Однако, если автор команды не определил типы вывода, информация о типе вывода будет неполной. Вы можете добавить информацию о типе вывода в файл Markdown. Update-MarkdownCommandHelp Добавляет только информацию о типе вывода, которую можно проверить, но не удаляет существующую информацию о типе вывода.

• Аналогично, некоторые параметры позволяют использовать выражения с подстановочными знаками. Если автор команды добавил [SupportsWildcards()] атрибут в параметр, эта информация будет правильно отражена в файле Markdown. Однако авторы команд очень часто опускают этот атрибут. Вы можете изменить информацию о параметре в файле Markdown, чтобы указать, что подстановочные знаки поддерживаются. Вы должны убедиться, что обновленная информация верна.

Для достижения наилучших результатов используйте средство сравнения файлов, чтобы сравнить обновленные файлы с файлами резервных копий. Вы можете проводить параллельные сравнения с помощью Visual Studio Code или средства сравнения, такого как Beyond Compare.

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

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

В следующей статье описывается структура файлов Markdown и способы обеспечения того, чтобы содержимое соответствовало ожидаемому формату.

• Редактирование файлов справки Markdown