Comment formater et nommer les exemples dans ma documentation de script PowerShell?

Question

Je voudrais appliquer le même style de documentation pour les exemples de script à mes scripts, ce qui est fréquemment démontré dans la documentation native. À titre d'exemple, considérez l'aide pour la commande Invoke-Command.

Get-Help Invoke-Command -Examples 

La sortie de cette commande contient les éléments suivants:

Example 3: Run a command in a persistent connection 

PS C:\>$s = New-PSSession -ComputerName Server02 -Credential Domain01\User01 
PS C:\> Invoke-Command -Session $s -ScriptBlock {Get-Culture} 

Comment dois-je nommer mes exemples pour qu'ils apparaissent comme ci-dessus au lieu de l'en-tête par défaut -------------------------- EXAMPLE 3 --------------------------? Ce dernier est rendu lors de l'utilisation d'une directive .EXAMPLE dans la balise de documentation.

En outre, comment puis-je tirer parti des exemples multi-lignes afin qu'ils incluent le préfixe de chemin de shell (PS C:\?). Je peux entrer manuellement ce préfixe dans ma documentation pour créer l'effet mais je me demandais s'il y avait une méthode différente et plus conforme.

Answer 1

Pour ce faire, utilisez un fichier XML MAML d'aide externe. Créée à la main ou en utilisant le module PlatyPS pour créer MAML à partir de démarquer. Vous pouvez également utiliser PlatyPS pour créer une démarque à partir de l'aide basée sur les commentaires (CBH).

PlatyPS Utilisation:

# Create markdown from CBH in a module 
New-MarkdownHelp -Module MyModule -OutputFolder .\docs -Locale en-US 

# Create MAML external help, usually in a build step 
New-ExternalHelp -Path .\docs -OutputPath .\moduleOutFolder\en-US 

# Then you can optionally replace the CBH with a link to the external help 
# file so you only need to adjust the markdown 

<# 
.EXTERNALHELP MyModuleName-help.xml 
#> 

Lors de la création du démarquage initial, vous devrez probablement ajuster manuellement le démarquage des exemples de plusieurs lignes. Pour cette raison et quelques autres différences de préférence, je maintiens habituellement seulement la démarque et remplace le CBH.