PHWriter(Powershell Help Writer) is a PowerShell module designed to generate beautifully formatted, colored help text for your PowerShell cmdlets, mimicking the style and readability of Linux man pages. It allows you to define your cmdlet's parameters and their descriptions in a structured way, providing a consistent and professional look for your command-line help. Features
- Customizable Layout: Control indentation and spacing between parameter elements.
- Colored Output: Enhance readability with distinct colors for different help sections and parameter components.
- ASCII Art Logo: Includes a simple, elegant ASCII art banner for visual appeal, or you can provide your own ascii art.
- Inline/Newline Descriptions: Choose whether parameter descriptions appear on the same line or a new line.
- Automatic Alignment: Dynamically calculates padding to ensure perfect alignment of parameter types and descriptions.
- Production Ready: Comes with a module manifest (.psd1) for proper PowerShell module management.
Phellams modules are available from PowerShell Gallery and Chocolatey. you can access the raw assets via Gitlab Generic Assets or nuget repository via Gitlab Packages.
| ▓▓▓▓▒▒▒▒░░░ | ▓▓▓▓▒▒▒▒░░░ | ▓▓▓▓▒▒▒▒░░░ |
|---|---|---|
| 📦 PSGallery |  |  |
| 📦 Chocolatey |  |  |
| ▓▓▓▓▒▒▒▒░░░ | ▓▓▓▓▒▒▒▒░░░ | ▓▓▓▓▒▒▒▒░░░ |
|---|---|---|
| 💼 Releases/Tags |  |  |
Using nuget: See the packages page for installation instructions.
For instructions on adding
nugetsources packages from GitLab see Releases artifacts or via the Packages page.
The latest release artifacts can be downloaded from the Generic Assets Artifacts page.
# Clone the repository
git clone https://gitlab.com/phellams/phwriter.git
cd phwriter
import-module .\# Import module from module directoryImport-Module-name PhwriterThe primary cmdlet provided by this module is New-PHWriter. Generates formatted help text based on an array of hashtables defining your cmdlet's parameters.
🔹 Output help text
New-PHWriter-Help🔹 Generate New Help
New-PHWriter-Name <String>`-CommandInfo <Hashtable>`-ParamTable <HashTable[]>`-Version <String>`-Examples <String[]>`-Padding <Int>`-Indent <Int>`-CustomLogo <String>-Help <Switch>- Name: The name of the module to display in the header. Default: "P H W R I T E R"
- CommandInfo: A hashtable containing the name and description of the cmdlet to display version information. Default: Current command name props: 'ModuleName', 'Cmdlet', 'Description'
- ParamTable: An array of hashtables defining the parameters and their descriptions. Default: Empty array
- Examples: An array of examples for the cmdlet. Default: Empty array
- Version: The version of the module to display in the header. Default: "1.0.0"
- Padding: The number of spaces between the parameter alias/name, type, and description. Default: 4
- Indent: The number of spaces to indent the help text. Default: 2
- CustomLogo: The logo to display at the top of the help text. Default: "P H W R I T E R"
- Help: Display help for the cmdlet
Outputs the header logo for the module
Write-PHAsciiLogo-Name <String># Has a Max char lengthYou can call New-PHWriter to generate help text for your cmdlet with the following parameters either by using params, params via hashtable
# Define the parameters for your custom cmdlet's help
[hashtable] $MyCommandDiscription=@{
cmdlet="New-PHWriter";
synopsis="New-PHWriter [-HelpTable <Hashtable[]>] [-Padding <Int>] [-Indent <Int>]";
description="This cmdlet generates formatted help text for PowerShell cmdlets with custom layouts and coloring, mimicking the style of the 'help' command. It supports custom layouts, coloring, and inline/newline descriptions. "; }
$myCmdletParams=@(
@{
Name="SourcePath"Param="s|Source"Type="string"required=$trueDescription="Specifies the source path for the operation. Wildcards are supported."Inline=$false# Description on a new line
},@{
Name="DestinationPath"Param="d|Destination"Type="string"required=$trueDescription="Specifies the destination path where files will be copied."Inline=$false# Description on the same line
},@{
Name="Recurse"Param="r|Recurse"Type="switch"required=$falseDescription="Indicates that the operation should process subdirectories recursively."Inline=$false
},@{
Name="Confirmation"Param="c|Confirm"Type="switch"required=$falseDescription="Prompts you for confirmation before running the cmdlet. (CommonParameter)"Inline=$false
}
)
$myCmdletexamples=@(
"New-PHWriter -SourcePath 'C:\Source' -DestinationPath 'C:\Destination' -Recurse","New-PHWriter -SourcePath 'C:\Source\*' -DestinationPath 'C:\Destination' -Confirm","New-PHWriter -SourcePath 'C:\Source' -DestinationPath 'C:\Destination' -Recurse -Confirm","New-PHWriter -SourcePath 'C:\Source\*' -DestinationPath 'C:\Destination' -Recurse -Confirm"
)🟢 Call PHWriter with params
New-PHWriter-Name "PHWRITER"`-ParamTable $myCmdletParams`-CommandInfo $MyCommandDiscription`-Examples $myCmdletexamples`-Version "1.2.1"`-Padding 6`-Indent 2$phwriter_object=@{
Name="PHWRITER"Version="1.2.1"Padding=6Indent=2CommandInfo=@{
cmdlet="New-PHWriter";
synopsis="New-PHWriter [-HelpTable <Hashtable[]>] [-Padding <Int>] [-Indent <Int>]";
description="This cmdlet generates formatted help text for PowerShell cmdlets with custom layouts and coloring, mimicking the style of the 'help' command. It supports custom layouts, coloring, and inline/newline descriptions. "; }
ParamTable=@(
@{
Name="SourcePath"Param="s|Source"Type="string"required=$trueDescription="Specifies the source path for the operation. Wildcards are supported."Inline=$false# Description on a new line
},@{
Name="DestinationPath"Param="d|Destination"Type="string"required=$trueDescription="Specifies the destination path where files will be copied."Inline=$false# Description on the same line
},@{
Name="Recurse"Param="r|Recurse"Type="switch"required=$falseDescription="Indicates that the operation should process subdirectories recursively."Inline=$false
},@{
Name="Confirmation"Param="c|Confirm"Type="switch"required=$falseDescription="Prompts you for confirmation before running the cmdlet. (CommonParameter)"Inline=$false
}
)
Examples=@(
"New-PHWriter -SourcePath 'C:\Source' -DestinationPath 'C:\Destination' -Recurse","New-PHWriter -SourcePath 'C:\Source\*' -DestinationPath 'C:\Destination' -Confirm","New-PHWriter -SourcePath 'C:\Source' -DestinationPath 'C:\Destination' -Recurse -Confirm","New-PHWriter -SourcePath 'C:\Source\*' -DestinationPath 'C:\Destination' -Recurse -Confirm"
)
}🟢 Call PHWriter with hashtable params
New-PHWriter@phwriter_objectsGenerate the formatted help output with custom padding and indent:
New-PHWriter-HelpTable $myCmdletParams-Padding 6-Indent 2Output
╔═======════════════════════════════════════════════════════════======═╗
╟░░░░░░░░░░░░░░░░░░░░░░░░░░░░P H W R I T E R░░░░░░░░░░░░░░░░░░░░░░░░░░░╢ ╚═======════════════════════════════════════════════════════════======═╝
MODULE PHWRITER CMDLET New-PHWriter v1.2.1
CMDLET SYNOPSIS
New-PHWriter [-HelpTable <Hashtable[]>] [-Padding <Int>] [-Indent <Int>]
DESCRIPTION
This cmdlet generates formatted help text for PowerShell cmdlets with custom layouts and
coloring, mimicking the style of the 'help' command. It supports custom layouts, coloring, and
inline/newline descriptions.
PARAMETERS
-s|Source [string] (Req) SourcePath
Specifies the source path for the operation. Wildcards are supported.
-d|Destination [string] (Req) DestinationPath
Specifies the destination path where files will be copied.
-r|Recurse [switch] Recurse
Indicates that the operation should process subdirectories recursively.
-c|Confirm [switch] Confirmation
Prompts you for confirmation before running the cmdlet. (CommonParameter)
EXAMPLES
New-PHWriter -SourcePath 'C:\Source' -DestinationPath 'C:\Destination' -Recurse
New-PHWriter -SourcePath 'C:\Source\*' -DestinationPath 'C:\Destination' -Confirm
New-PHWriter -SourcePath 'C:\Source' -DestinationPath 'C:\Destination' -Recurse -Confirm
New-PHWriter -SourcePath 'C:\Source\*' -DestinationPath 'C:\Destination' -Recurse -Confirm
🟡 Task List
- Add parameter validation as mandatory is not use,
modulename -helpneeds to be called - Add Advance Parameter Section in output, make it optional
Feel free to contribute! Fork the repo and submit a merge request with your improvements. Or, open an issue with the enhancement tag to discuss your ideas.
- Fork the Project from
git clone https://gitlab.com/phellams/phwriter.git - Create your Feature Branch check out the branch dev
git switch dev.git switch -c feature/AmazingFeature- or
git checkout -b feature/AmazingFeature
- Commit your Changes
git commit -m 'Add some AmazingFeature' - Push to the Branch
git push origin feature/AmazingFeature - Open a Merge Request
This project is licensed under the MIT License - see the LICENSE file for details.