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 потребует некоторого ручного редактирования, но то же самое делает редактор справки cmdlet, на который вы ссылались. У меня есть запись в блоге об этом здесь

Если вы используете его и найдете исправления, не стесняйтесь обновить скрипт на 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

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

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

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

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

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

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

Answer 4

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

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

Answer 5

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