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

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

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

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

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

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

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

Answer 3

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

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

Answer 5

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

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