Генератор справочных данных PowerShell MAML
-
23-09-2019 - |
Вопрос
Кто-нибудь знает утилиту для создания файлов справки командлета PowerShell?Делать это вручную кажется немного утомительным...
Я обнаружил: http://blogs.msdn.com/powershell/archive/2007/09/01/new-and-improved-cmdlet-help-editor-tool.aspx
Есть какие-нибудь обновленные версии?Я не могу выбрать модуль.У меня есть двоичный модуль.
Решение
Я создал сценарий Powershell, который генерирует MAML для командлетов и функций независимо от того, являются ли они частью модулей.Это не идеально, поскольку сгенерированный MAML потребует некоторого редактирования вручную, но то же самое можно сказать и о редакторе справки командлета, на который вы ссылались.У меня есть запись в блоге об этом здесь
Если вы используете его и найдете исправления, не стесняйтесь обновлять скрипт на PoshCode.
Другие советы
Мне пришлось документировать свой модуль, и я не нашел лучшего решения, чем создать собственный конструктор справки MAML.Вот:https://github.com/nightroman/Helps
Модуль создает файлы справки PowerShell MAML из сценариев справки PowerShell.Скрипты справки почти WYSIWYG, они очень похожи на результат справки.Тем не менее, это всего лишь сценарии, и это упрощает работу со многими полезными функциями.Один из них — создание файлов справки для нескольких культур.
Вот шаблон справочных данных для команд (командлетов, функций, скриптов) и поставщиков:
### Command help data
@{
command = 'Name'
synopsis = '...'
description = '...'
sets = @{
Set1 = '...'
#...
}
parameters = @{
Param1 = '...'
#...
}
inputs = @(
@{
type = '...'
description = '...'
}
#...
)
outputs = @(
@{
type = '...'
description = '...'
}
#...
)
notes = '...'
examples = @(
@{
title = '...'
introduction = '...'
code = {
}
remarks = '...'
test = {
. $args[0]
}
}
#...
)
links = @(
@{
text = '...'
URI = '...'
}
#...
)
}
### Provider help data
@{
provider = 'Name'
drives = '...'
synopsis = '...'
description = '...'
capabilities = '...'
tasks = @(
@{
title = '...'
description = '...'
examples = @(
@{
title = '...'
introduction = '...'
code = {
}
remarks = '...'
test = {
. $args[0]
}
}
)
}
#...
)
parameters = @(
@{
name = '...'
type = '...'
description = '...'
cmdlets = '...'
values = @(
@{
value = '...'
description = '...'
}
#...
)
}
#...
)
notes = '...'
links = @(
@{
text = '...'
URI = '...'
}
#...
)
}
Я искал способ встроить документацию в код оснастки/модуля C# и Пошбилд начинает выглядеть как мой лучший вариант.Он не позволяет включать некоторые элементы документации (например, краткий обзор и примеры), но все же это хороший вариант.
Что касается графических инструментов для редактирования справки XML PowerShell (PSMAML), вы можете использовать:
- Редактор справки по командлетам PowerShell (Открытый исходный код, своего рода духовный преемник редактора справки Cmdlet).
- PowerShell HelpWriter (Коммерческий).
С появлением системы с открытым исходным кодом XmlDoc2CmdletDoc, теперь вы можете задокументировать свой двоичный код Командлеты PowerShell (т.е.те, что написаны на C #) точно так же, как и любые другие библиотеки C #, и точно так же, как написанный по сценарию командлеты (написанные в PowerShell):используйте встроенные комментарии к документации.
Вам больше не нужно поддерживать параллель МАМЛ напильник вручную!Просто настройте свою сборку так, чтобы при перекомпиляции вашего проекта на C # он запускал генератор документации, и вы получали оба модуль.библиотека dll и еще модуль.dll-Help.xml.Последний непосредственно используется PowerShell для предоставления справки по вашим командлетам при вызове Get-Help
.
А XmlDoc2CmdletDoc даже предлагает -strict
переключитесь, чтобы убедиться, что вы полностью задокументировали свои командлеты;если вы используете переключатель и что-то пропустили, ваша сборка завершится неудачей, как и должно быть.
Другие преимущества, автоматически предоставляемые XmlDoc2CmdletDoc ("разделы" в этом списке относятся к разделам справки, представленным Get-Help
):
- Каждый пользовательский тип в Результаты раздел включает в себя описание.
- Тот Самый Синтаксис раздел содержит возможные значения для перечисленных типов.
- Тот Самый Параметр раздел содержит возможные значения для перечисленных типов.
- Псевдонимы автоматически документируются в Параметры Раздел.
- Псевдонимы рассматриваются как первоклассные параметры, поэтому вы можете обратиться за помощью по поводу псевдонима.
- При необходимости вы можете использовать другое описание для параметра в Входные данные раздел, как у вас есть для Параметр Раздел.
- Веб-ссылки автоматически отображаются в формате markdown для возможной последующей обработки живых ссылок.(Это улучшение находится на рассмотрении.)
Мне так понравилась эта утилита с открытым исходным кодом, что я начал вносить в нее свой вклад, предоставляя некоторые из вышеперечисленных преимуществ.И я написал всеобъемлющее руководство по его использованию, озаглавленное Документирование ваших двоичных командлетов PowerShell, только что опубликованный на Simple-Talk.com.