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
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.
There isn’t one. The docs folder is meant to do two things
House the markdown files for New-ExternalHelp later
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)
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!