platyps external help with Markdown

This topic contains 6 replies, has 2 voices, and was last updated by  Kevin Greer 1 month ago.

  • Author
    Posts
  • #75356

    Kevin Greer
    Participant

    I'm studying PowerShell Scripting and ToolMaking and I'm stuck on using Platyps to create external help. Perhaps someone can help me understand what I'm doing wrong. thank you!

    Within my tool Module folder I created a Docs directory and ran New-Markdownhelp -module exptools -outputfolder .\docs\ -withmodulepage. It worked. I see all of my commands with their associated .md files and the ones that had comment based help is populated in the .md file so I figured I could delete the comment based help from one of my functions, reload my exptools module then run get-help get-expOffice. the only help I see is the basic PowerShell generated help when there is no comment based help. What am I missing to get PowerShell to read help files from my docs folder?

    Note: my module was generated by ISE Steroids so I have a tools.psd1 file, loader.psm1, init.ps1, and all of my functions have their own .ps1 file.

    tools.psd1

    #
    # Module Manifest for Module 'expTools.psd1
    #
    # This manifest file is a PowerShell hashtable with all technical requirements for this module
    # This module was autogenerated by ISESteroids (http://www.isesteroids.com)
    #
    # Generated: 2017-07-20
    #
    
    @{
    
    # Module Loader File
    RootModule = 'loader.psm1'
    
    # Version Number
    ModuleVersion = '1.12'
    
    # Unique Module ID
    GUID = '2e461e51-7fa5-4828-8fa5-6d3629eef9e3'
    
    # Module Author
    Author = 'kgreer'
    
    # Company
    CompanyName = 'kgreer'
    
    # Copyright
    Copyright = '(c) 2017 kgreer. All rights reserved.'
    
    # Module Description
    Description = 'various IS tools'
    
    # Minimum PowerShell Version Required
    PowerShellVersion = ''
    
    # Name of Required PowerShell Host
    PowerShellHostName = ''
    
    # Minimum Host Version Required
    PowerShellHostVersion = ''
    
    # Minimum .NET Framework-Version
    DotNetFrameworkVersion = ''
    
    # Minimum CLR (Common Language Runtime) Version
    CLRVersion = ''
    
    # Processor Architecture Required (X86, Amd64, IA64)
    ProcessorArchitecture = ''
    
    # Required Modules (will load before this module loads)
    RequiredModules = @()
    
    # Required Assemblies
    RequiredAssemblies = @()
    
    # PowerShell Scripts (.ps1) that need to be executed before this module loads
    ScriptsToProcess = @()
    
    # Type files (.ps1xml) that need to be loaded when this module loads
    TypesToProcess = @()
    
    # Format files (.ps1xml) that need to be loaded when this module loads
    FormatsToProcess = @()
    
    # 
    NestedModules = @()
    
    # List of exportable functions
    FunctionsToExport = '*'
    
    # List of exportable cmdlets
    CmdletsToExport = '*'
    
    # List of exportable variables
    VariablesToExport = '*'
    
    # List of exportable aliases
    AliasesToExport = '*'
    
    # List of all modules contained in this module
    ModuleList = @()
    
    # List of all files contained in this module
    FileList = @()
    
    # Private data that needs to be passed to this module
    PrivateData = ''
    
    }
    

    loader.psm1

    # DO NOT MODIFY THIS FILE!
    # THIS FILE WAS AUTOGENERATED BY ISESTEROIDS AND WILL BE OVERWRITTEN WHEN YOU EXPORT FUNCTIONS TO THIS MODULE.
    
    # USE THIS FILE FOR ADDITIONAL MODULE CODE. THIS FILE WILL NOT BE OVERWRITTEN
    # WHEN NEW CONTENT IS PUBLISHED TO THIS MODULE:
    . $PSScriptRoot\init.ps1
    
    
    # LOADING ALL FUNCTION DEFINITIONS:
    
    . $PSScriptRoot\Find-expDeletedComputer.ps1
    . $PSScriptRoot\get-expCimProtocol.ps1
    . $PSScriptRoot\Get-expOffice.ps1
    . $PSScriptRoot\Get-expOfficeDomainController.ps1
    . $PSScriptRoot\Get-expOfficeLastKnownParent.ps1
    . $PSScriptRoot\Get-expUserGroup.ps1
    . $PSScriptRoot\Move-expObject.ps1
    . $PSScriptRoot\New-expCimSession.ps1
    . $PSScriptRoot\Restore-expComputer.ps1
    . $PSScriptRoot\Set-expComputerDescription.ps1
    . $PSScriptRoot\Test-expComputerAccess.ps1
    

    My init.ps1 file is empty

  • #75362

    Patrick Meinecke
    Participant

    You're missing the step where you generate the MAML XML file from the markdown. Typically as a task in a build script.

    New-ExternalHelp -OutputPath .\your\module\out\dir -Path .\docs

    Also in your functions, make sure you still have comment help that points to the external file.

        #
        .EXTERNALHELP EditorServicesCommandSuite-help.xml
        #

    (Add less than and greater than signs to make it a block comment as usual. Not sure how to escape them in this markup.)

  • #75368

    Kevin Greer
    Participant

    I did that, but I get a bunch of exceptions. I don't have a location set for 'download help link' in the exptools.md file and thought New-ExternalHelp was for that. I want internal help to read the help files in the docs folder or en-us folder... I'm confused.

    PS C:\Users\kgreer\documents\windowspowershell\modules\exptools> Get-ChildItem -Directory
    
    
        Directory: C:\Users\kgreer\documents\windowspowershell\modules\exptools
    
    
    Mode                LastWriteTime         Length Name
    ----                -------------         ------ ----
    d-----        7/20/2017   2:56 PM                Docs
    d-----        7/20/2017   3:30 PM                en-us
    
    PS C:\Users\kgreer\documents\windowspowershell\modules\exptools> New-ExternalHelp -Path .\docs\ -OutputPath .\en-us\
    Exception calling "NodeModelToMamlModel" with "1" argument(s):
    "C:\Users\kgreer\documents\windowspowershell\modules\exptools\docs\Find-expDeletedComputer.md:66:(354)
    '[Get-expOfficeLastKnownParent
    Get-ADObject]()
    ...'
     Expect hyperlink, but got [Get-expOfficeLastKnownParent Get-ADObject]()"
    At C:\Program Files\WindowsPowerShell\Modules\platyPS\0.8.1\platyPS.psm1:1372 char:9
    +         $maml = $t.NodeModelToMamlModel($model)
    +         ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        + CategoryInfo          : NotSpecified: (:) [], MethodInvocationException
        + FullyQualifiedErrorId : HelpSchemaException
    
    SetOnlineVersionUrlLink : Cannot bind argument to parameter 'MamlCommandObject' because it is null.
    At C:\Program Files\WindowsPowerShell\Modules\platyPS\0.8.1\platyPS.psm1:1379 char:60
    +                 SetOnlineVersionUrlLink -MamlCommandObject $_ -Online ...
    +                                                            ~~
        + CategoryInfo          : InvalidData: (:) [SetOnlineVersionUrlLink], ParameterBindingValidationException
        + FullyQualifiedErrorId : ParameterArgumentValidationErrorNullNotAllowed,SetOnlineVersionUrlLink
    
    Exception calling "NodeModelToMamlModel" with "1" argument(s):
    "C:\Users\kgreer\documents\windowspowershell\modules\exptools\docs\Test-expComputerAccess.md:53:(176) '[URLs to
    related sites
    The first link is opened b...'
     Expect hyperlink, but got [URLs to related sites The first link is opened by Get-Help -Online
    Test-expComputerAccess]()"
    At C:\Program Files\WindowsPowerShell\Modules\platyPS\0.8.1\platyPS.psm1:1372 char:9
    +         $maml = $t.NodeModelToMamlModel($model)
    +         ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        + CategoryInfo          : NotSpecified: (:) [], MethodInvocationException
        + FullyQualifiedErrorId : HelpSchemaException
    
    Exception calling "MamlModelToString" with "1" argument(s): "Object reference not set to an instance of an object."
    At C:\Program Files\WindowsPowerShell\Modules\platyPS\0.8.1\platyPS.psm1:769 char:13
    +             $xml = $r.MamlModelToString($maml)
    +             ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        + CategoryInfo          : NotSpecified: (:) [], MethodInvocationException
        + FullyQualifiedErrorId : NullReferenceException
    
    MySetContent : Cannot bind argument to parameter 'value' because it is an empty string.
    At C:\Program Files\WindowsPowerShell\Modules\platyPS\0.8.1\platyPS.psm1:773 char:48
    +             MySetContent -Path $outPath -Value $xml -Encoding $Encodi ...
    +                                                ~~~~
        + CategoryInfo          : InvalidData: (:) [MySetContent], ParameterBindingValidationException
        + FullyQualifiedErrorId : ParameterArgumentValidationErrorEmptyStringNotAllowed,MySetContent
    
    • #75370

      Patrick Meinecke
      Participant

      The entries in the RelatedLinks section at the bottom of the markdown files need to be links. For example, if you currently have

      ## RELATED LINKS
      
      Get-expOfficeLastKnownParent
      

      You need to change it to

      ## RELATED LINKS
      
      [Get-expOfficeLastKnownParent](Get-expOfficeLastKnownParent.md)
      

      For external links, do the same but replace

      FileName.md

      with the URL.

      Also "Download Help Link" is for updatable help. You can safely leave it blank, I haven't set it up in any of my projects yet either.

  • #75371

    Kevin Greer
    Participant

    Still not getting results. What is the mechanism that tells PowerShell that my module has help files in the docs folder?

    • #75374

      Patrick Meinecke
      Participant

      There isn't one. The docs folder is meant to do two things

      1. House the markdown files for New-ExternalHelp later
      2. Display an online version of help in repositories like GitHub

      You aren't meant to actually include the docs folder with the release of your module. You include the XML file generated from New-ExternalHelp. The way PowerShell knows to look for said external help file is with the .EXTERNALHELP tag in comment based help.

      Look at the comment based help of this file for reference.

      (Side note: they do plan to add the ability to consume markdown help natively, but the PowerShell engine does not currently have a way to do so. It must be converted into MAML first)

  • #75379

    Kevin Greer
    Participant

    I think I got it. The exceptions were due to poor formatting in the related section of the .md files. I think you were trying to tell me that, but it just clicked. Thank you for the help!

You must be logged in to reply to this topic.