Générateur d'aide PowerShell MAML

Question

Quelqu'un connaît-il un utilitaire permettant de générer des fichiers d'aide pour les applets de commande PowerShell ?Le faire à la main semble un peu fastidieux...

J'ai localisé : http://blogs.msdn.com/powershell/archive/2007/09/01/new-and-improved-cmdlet-help-editor-tool.aspx

Des versions mises à jour ?Je ne parviens pas à sélectionner un module.J'ai un module binaire.

Answer 1

J'ai créé un script Powershell qui va générer GAML pour cmdlets et fonctions indépendamment du fait qu'ils partie des modules. Ce n'est pas parfait comme le GAML généré nécessitera une modification manuelle, mais le fait l'éditeur d'aide cmdlet vous avez fait référence. J'ai un blog sur ce

Si vous l'utilisez et de trouver des corrections ne hésitez pas à mettre à jour le script sur PoshCode.

Answer 2

Je devais documenter mon module et n'a pas trouvé une meilleure solution que de créer mon propre constructeur d'aide GAML. C'est ici: https://github.com/nightroman/Helps

Le module construit fichiers d'aide PowerShell maml à partir de scripts d'aide PowerShell. scripts d'aide sont presque WYSIWYG, ils ressemblent beaucoup à l'aide des résultats. Pourtant, ils ne sont que des scripts et cela fait beaucoup de fonctionnalités utiles facile. L'un d'eux est la construction de fichiers d'aide pour plusieurs cultures.

Voici le modèle de données d'aide pour les commandes (applet de commande, fonctions, scripts) et les fournisseurs:

### 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

J'ai regardé un moyen d'intégrer la documentation dans le snapin / module de code C # et PoshBuild commence à ressembler à ma meilleure option. Il ne fournit pas un moyen d'inclure certains des éléments de documentation (par exemple, synopsis et exemples), mais il est toujours une bonne option.

Answer 4

En termes d'outils graphiques pour l'aide de PowerShell XML d'édition (PSMAML) vous pouvez utiliser:

• PowerShell Cmdlet Aide éditeur (Open Source, quelque chose d'un successeur spirituel de Cmdlet Aide Editor).
• PowerShell HelpWriter (commerciale).

Answer 5

Avec l'avènement de l'open source XmlDoc2CmdletDoc, vous pouvez désormais documenter votre binaire Applets de commande PowerShell (c'est-à-direcelles écrites en C#) comme toutes les autres bibliothèques C#, et tout comme scripté applets de commande (ceux écrits en PowerShell) :utilisez les commentaires de la documentation en ligne.

Vous n'avez plus besoin de maintenir un parallèle MAML limer à la main !Instrumentez simplement votre build de sorte que lorsque vous recompilez votre projet C#, il exécute le générateur de documentation et vous obteniez à la fois un module.dll et un module.dll-Aide.xml.Ce dernier est directement utilisé par PowerShell pour fournir de l'aide sur vos applets de commande lorsque vous invoquez Get-Help.

Et XmlDoc2CmdletDoc propose même un -strict basculez pour vous assurer que vous avez documenté de manière exhaustive vos applets de commande ;si vous utilisez le commutateur et que vous avez manqué quelque chose, votre build échouera, comme il se doit.

Autres avantages automatiquement fournis par XmlDoc2CmdletDoc (les « sections » dans cette liste font référence aux sections d'aide présentées par Get-Help):

• Chaque type personnalisé dans le Les sorties La section comprend une description.
• Le Syntaxe La section inclut les valeurs possibles pour les types énumérés.
• Le Paramètre La section inclut les valeurs possibles pour les types énumérés.
• Les alias sont documentés automatiquement dans le Paramètres section.
• Les alias sont traités comme des paramètres de premier ordre afin que vous puissiez demander de l'aide sur un alias.
• Vous pouvez éventuellement utiliser une description différente pour un paramètre dans le Contributions section comme vous l'avez fait pour la Paramètre section.
• Les liens Web sont automatiquement rendus au format markdown, pour un éventuel post-traitement vers des liens en direct.(Cette amélioration est en attente.)

J'ai tellement aimé cet utilitaire open source que j'ai commencé à y contribuer, offrant plusieurs des avantages ci-dessus.Et j'ai écrit un guide complet sur son utilisation, intitulé Documenter vos applets de commande binaires PowerShell, vient de paraître sur Simple-Talk.com.