Генератор справочных данных PowerShell MAML

Question

Кто-нибудь знает утилиту для создания файлов справки командлета PowerShell?Делать это вручную кажется немного утомительным...

Я обнаружил: http://blogs.msdn.com/powershell/archive/2007/09/01/new-and-improved-cmdlet-help-editor-tool.aspx

Есть какие-нибудь обновленные версии?Я не могу выбрать модуль.У меня есть двоичный модуль.

Answer 1

Я создал сценарий Powershell, который генерирует MAML для командлетов и функций независимо от того, являются ли они частью модулей.Это не идеально, поскольку сгенерированный MAML потребует некоторого редактирования вручную, но то же самое можно сказать и о редакторе справки командлета, на который вы ссылались.У меня есть запись в блоге об этом здесь

Если вы используете его и найдете исправления, не стесняйтесь обновлять скрипт на PoshCode.

Answer 2

Мне пришлось документировать свой модуль, и я не нашел лучшего решения, чем создать собственный конструктор справки 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 = '...'
        }
        #...
    )
}

Answer 3

Я искал способ встроить документацию в код оснастки/модуля C# и Пошбилд начинает выглядеть как мой лучший вариант.Он не позволяет включать некоторые элементы документации (например, краткий обзор и примеры), но все же это хороший вариант.

Answer 4

Что касается графических инструментов для редактирования справки XML PowerShell (PSMAML), вы можете использовать:

• Редактор справки по командлетам PowerShell (Открытый исходный код, своего рода духовный преемник редактора справки Cmdlet).
• PowerShell HelpWriter (Коммерческий).

Answer 5

С появлением системы с открытым исходным кодом XmlDoc2CmdletDoc, теперь вы можете задокументировать свой двоичный код Командлеты PowerShell (т.е.те, что написаны на C #) точно так же, как и любые другие библиотеки C #, и точно так же, как написанный по сценарию командлеты (написанные в PowerShell):используйте встроенные комментарии к документации.

Вам больше не нужно поддерживать параллель МАМЛ напильник вручную!Просто настройте свою сборку так, чтобы при перекомпиляции вашего проекта на C # он запускал генератор документации, и вы получали оба модуль.библиотека dll и еще модуль.dll-Help.xml.Последний непосредственно используется PowerShell для предоставления справки по вашим командлетам при вызове Get-Help.

А XmlDoc2CmdletDoc даже предлагает -strict переключитесь, чтобы убедиться, что вы полностью задокументировали свои командлеты;если вы используете переключатель и что-то пропустили, ваша сборка завершится неудачей, как и должно быть.

Другие преимущества, автоматически предоставляемые XmlDoc2CmdletDoc ("разделы" в этом списке относятся к разделам справки, представленным Get-Help):

• Каждый пользовательский тип в Результаты раздел включает в себя описание.
• Тот Самый Синтаксис раздел содержит возможные значения для перечисленных типов.
• Тот Самый Параметр раздел содержит возможные значения для перечисленных типов.
• Псевдонимы автоматически документируются в Параметры Раздел.
• Псевдонимы рассматриваются как первоклассные параметры, поэтому вы можете обратиться за помощью по поводу псевдонима.
• При необходимости вы можете использовать другое описание для параметра в Входные данные раздел, как у вас есть для Параметр Раздел.
• Веб-ссылки автоматически отображаются в формате markdown для возможной последующей обработки живых ссылок.(Это улучшение находится на рассмотрении.)

Мне так понравилась эта утилита с открытым исходным кодом, что я начал вносить в нее свой вклад, предоставляя некоторые из вышеперечисленных преимуществ.И я написал всеобъемлющее руководство по его использованию, озаглавленное Документирование ваших двоичных командлетов PowerShell, только что опубликованный на Simple-Talk.com.