PHWriter

Overview

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.

Installation

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

Additinonal Installation Options:

▓▓▓▓▒▒▒▒░░░	▓▓▓▓▒▒▒▒░░░	▓▓▓▓▒▒▒▒░░░
💼 Releases/Tags

📦 GitLab Packages

Using nuget: See the packages page for installation instructions.

For instructions on adding nuget sources packages from GitLab see Releases artifacts or via the Packages page.

🧺 Generic Asset

The latest release artifacts can be downloaded from the Generic Assets Artifacts page.

💾 Git Clone

# Clone the repository
git clone https://gitlab.com/phellams/phwriter.git
cd phwriter
import-module .\

Quick Start

# Import module from module directory
Import-Module -name Phwriter

Usage

The primary cmdlet provided by this module is New-PHWriter. Generates formatted help text based on an array of hashtables defining your cmdlet's parameters.

🏮 New-PHWriter

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

Parameters List

• 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

🏮 Write-PHAsciiLogo

Outputs the header logo for the module

Write-PHAsciiLogo -Name <String> # Has a Max char length

Examples:

You can call New-PHWriter to generate help text for your cmdlet with the following parameters either by using params, params via hashtable

🟡 Option 1 By Variables

# 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   = $true
        Description = "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   = $true
        Description = "Specifies the destination path where files will be copied."
        Inline      = $false  # Description on the same line
    },
    @{
        Name        = "Recurse"
        Param       = "r|Recurse"
        Type        = "switch"
        required   = $false
        Description = "Indicates that the operation should process subdirectories recursively."
        Inline      = $false
    },
    @{
        Name        = "Confirmation"
        Param       = "c|Confirm"
        Type        = "switch"
        required   = $false
        Description = "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

🟡 Option 2 By Object Hashtable

$phwriter_object = @{
    Name =  "PHWRITER"
    Version =  "1.2.1"
    Padding =  6
    Indent =  2
    CommandInfo = @{
        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   = $true
            Description = "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   = $true
            Description = "Specifies the destination path where files will be copied."
            Inline      = $false  # Description on the same line
        },
        @{
            Name        = "Recurse"
            Param       = "r|Recurse"
            Type        = "switch"
            required   = $false
            Description = "Indicates that the operation should process subdirectories recursively."
            Inline      = $false
        },
        @{
            Name        = "Confirmation"
            Param       = "c|Confirm"
            Type        = "switch"
            required   = $false
            Description = "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_objects

Generate the formatted help output with custom padding and indent:

New-PHWriter -HelpTable $myCmdletParams -Padding 6 -Indent 2

Output

╔═======════════════════════════════════════════════════════════======═╗
╟░░░░░░░░░░░░░░░░░░░░░░░░░░░░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

Roadmap

🟡 Task List

• Add parameter validation as mandatory is not use, modulename -help needs to be called
• Add Advance Parameter Section in output, make it optional

Contributing

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.

1. Fork the Project from git clone https://gitlab.com/phellams/phwriter.git
2. Create your Feature Branch check out the branch dev git switch dev.
   1. git switch -c feature/AmazingFeature
   2. or
   3. git checkout -b feature/AmazingFeature
3. Commit your Changes git commit -m 'Add some AmazingFeature'
4. Push to the Branch git push origin feature/AmazingFeature
5. Open a Merge Request

📑 License

This project is licensed under the MIT License - see the LICENSE file for details.