Private/New-PstReadme.ps1
|
# Helper functions must be defined before main function for cross-platform compatibility # These are called by New-PstReadme and need to be in scope when the script is dot-sourced function Get-BasicReadmeContent { <# .SYNOPSIS Generates Basic complexity README content. #> [CmdletBinding()] [OutputType([string])] param( [Parameter(Mandatory = $true)] [string]$ModuleName, [Parameter(Mandatory = $true)] [string]$Description ) # Use single-quoted here-string and replace placeholders for cross-platform compatibility $template = @' # {{ModuleName}} ## Description {{Description}} ## Installation ```powershell # Clone the repository git clone https://github.com/username/{{ModuleName}}.git # Import the module Import-Module .\{{ModuleName}} ``` ## Usage ```powershell # Import the module Import-Module {{ModuleName}} # List available commands Get-Command -Module {{ModuleName}} ``` '@ $content = $template -replace '\{\{ModuleName\}\}', $ModuleName -replace '\{\{Description\}\}', $Description return $content } function Get-StandardReadmeContent { <# .SYNOPSIS Generates Standard complexity README content. #> [CmdletBinding()] [OutputType([string])] param( [Parameter(Mandatory = $true)] [string]$ModuleName, [Parameter(Mandatory = $true)] [string]$Description, [Parameter(Mandatory = $false)] [string]$Author, [Parameter(Mandatory = $false)] [string[]]$Functions = @() ) $functionList = if ($Functions.Count -gt 0) { ($Functions | ForEach-Object { "- ``$_``" }) -join "`n" } else { "- *Functions will be documented as they are added*" } # Use single-quoted here-string and replace placeholders for cross-platform compatibility $template = @' # {{ModuleName}} ## Description {{Description}} ## Features - Feature 1: Describe key functionality - Feature 2: Describe another feature - Feature 3: Additional capabilities ## Installation ### From Source ```powershell # Clone the repository git clone https://github.com/username/{{ModuleName}}.git # Import the module Import-Module ./src/{{ModuleName}} ``` ### From PowerShell Gallery (if published) ```powershell Install-Module -Name {{ModuleName}} -Scope CurrentUser ``` ## Usage ### Basic Usage ```powershell # Import the module Import-Module {{ModuleName}} # List available commands Get-Command -Module {{ModuleName}} ``` ### Examples ```powershell # Example 1: Basic operation # TODO: Add specific example # Example 2: Advanced usage # TODO: Add specific example ``` ## Available Commands {{FunctionList}} ## Parameters Each command supports standard PowerShell parameters including: - ``-Verbose``: Show detailed operation information - ``-Debug``: Show debug information - ``-WhatIf``: Preview changes without executing - ``-Confirm``: Prompt for confirmation before changes ## Contributing Contributions are welcome! Please follow these steps: 1. Fork the repository 2. Create a feature branch (``git checkout -b feature/YourFeature``) 3. Commit your changes (``git commit -m 'Add YourFeature'``) 4. Push to the branch (``git push origin feature/YourFeature``) 5. Open a Pull Request ## Author {{Author}} ## License This project is licensed under the MIT License - see the LICENSE file for details. '@ $content = $template -replace '\{\{ModuleName\}\}', $ModuleName ` -replace '\{\{Description\}\}', $Description ` -replace '\{\{FunctionList\}\}', $functionList ` -replace '\{\{Author\}\}', $Author return $content } function Get-AdvancedReadmeContent { <# .SYNOPSIS Generates Advanced complexity README content. #> [CmdletBinding()] [OutputType([string])] param( [Parameter(Mandatory = $true)] [string]$ModuleName, [Parameter(Mandatory = $true)] [string]$Description, [Parameter(Mandatory = $false)] [string]$Author, [Parameter(Mandatory = $false)] [string]$ProjectUri, [Parameter(Mandatory = $false)] [string[]]$Functions = @() ) $repoName = if ($ProjectUri) { $ProjectUri } else { "username/$ModuleName" } $badgeBase = if ($ProjectUri -match 'github\.com/([^/]+/[^/]+)') { $Matches[1] } else { "username/$ModuleName" } $functionList = if ($Functions.Count -gt 0) { ($Functions | ForEach-Object { "| ``$_`` | Description for $_ |" }) -join "`n" } else { "| *Commands* | *Will be documented as added* |" } # Use single-quoted here-string and replace placeholders for cross-platform compatibility $template = @' # {{ModuleName}} [](https://github.com/{{BadgeBase}}/actions) [](https://www.powershellgallery.com/packages/{{ModuleName}}) [](https://www.powershellgallery.com/packages/{{ModuleName}}) [](LICENSE) [](https://codecov.io/gh/{{BadgeBase}}) ## Description {{Description}} This module provides enterprise-grade PowerShell functionality with comprehensive testing, documentation, and CI/CD integration. ## Features - ✅ Feature 1: Describe key functionality - ✅ Feature 2: Describe another feature - ✅ Feature 3: Additional capabilities - ✅ Comprehensive error handling - ✅ Full pipeline support - ✅ 90%+ test coverage ## Architecture ``` {{ModuleName}}/ ├── src/ │ └── {{ModuleName}}/ │ ├── {{ModuleName}}.psd1 # Module manifest │ ├── {{ModuleName}}.psm1 # Root module │ ├── Public/ # Exported functions │ ├── Private/ # Internal functions │ └── Resources/ # Templates and assets ├── tests/ │ ├── Unit/ # Unit tests │ └── Integration/ # Integration tests ├── docs/ # Documentation ├── build.ps1 # Build script └── README.md ``` ## Requirements - **PowerShell**: 5.1+ or PowerShell 7+ - **Pester**: 5.0+ (for running tests) - **PSScriptAnalyzer**: Latest (for code analysis) ## Installation ### From PowerShell Gallery (Recommended) ```powershell Install-Module -Name {{ModuleName}} -Scope CurrentUser ``` ### From Source ```powershell # Clone the repository git clone https://github.com/{{BadgeBase}}.git cd {{ModuleName}} # Import the module Import-Module ./src/{{ModuleName}} ``` ### Using git submodule ```powershell git submodule add https://github.com/{{BadgeBase}}.git modules/{{ModuleName}} ``` ## Quick Start ```powershell # Import the module Import-Module {{ModuleName}} # Get help on available commands Get-Command -Module {{ModuleName}} | Get-Help # Run your first command # TODO: Add quick start example ``` ## Usage ### Example 1: Basic Operation ```powershell # Import the module Import-Module {{ModuleName}} # Basic usage # TODO: Add specific example with description ``` ### Example 2: Pipeline Usage ```powershell # Use with pipeline # TODO: Add pipeline example ``` ### Example 3: Advanced Configuration ```powershell # Advanced usage with all parameters # TODO: Add advanced example ``` ## API Documentation | Command | Description | |---------|-------------| {{FunctionList}} ### Detailed Command Help For detailed help on any command: ```powershell Get-Help <CommandName> -Full Get-Help <CommandName> -Examples ``` ## Development ### Prerequisites ```powershell # Install development dependencies Install-Module -Name Pester -MinimumVersion 5.0 -Force Install-Module -Name PSScriptAnalyzer -Force ``` ### Building ```powershell # Run the build script .\build.ps1 -Configuration Debug ``` ### Development Workflow 1. Create a feature branch 2. Make changes 3. Run tests locally 4. Submit pull request ## Testing ### Running All Tests ```powershell # Run all tests Invoke-Pester -Path ./tests/ # Run with code coverage Invoke-Pester -Path ./tests/ -CodeCoverage ./src/{{ModuleName}}/**/*.ps1 ``` ### Running Specific Tests ```powershell # Run unit tests only Invoke-Pester -Path ./tests/Unit/ # Run integration tests only Invoke-Pester -Path ./tests/Integration/ # Run tests with specific tags Invoke-Pester -Path ./tests/ -Tag 'Unit' ``` ### Code Analysis ```powershell # Run PSScriptAnalyzer Invoke-ScriptAnalyzer -Path ./src/ -Recurse -Settings ./PSScriptAnalyzerSettings.psd1 ``` ## Contributing We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details. ### Quick Contribution Steps 1. Fork the repository 2. Create a feature branch (``git checkout -b feature/AmazingFeature``) 3. Write tests for your changes 4. Ensure all tests pass 5. Commit your changes (``git commit -m 'Add AmazingFeature'``) 6. Push to the branch (``git push origin feature/AmazingFeature``) 7. Open a Pull Request ### Code Standards - Follow [PowerShell Best Practices](https://docs.microsoft.com/en-us/powershell/scripting/developer/cmdlet/cmdlet-development-guidelines) - Use approved verbs for function names - Include comment-based help for all public functions - Maintain 90%+ code coverage - Pass all PSScriptAnalyzer rules ## Changelog See [CHANGELOG.md](CHANGELOG.md) for a list of changes. ## Roadmap - [ ] Feature 1: Upcoming feature - [ ] Feature 2: Planned enhancement - [ ] Feature 3: Future consideration ## Support - 📖 [Documentation](docs/README.md) - 🐛 [Issue Tracker](https://github.com/{{BadgeBase}}/issues) - 💬 [Discussions](https://github.com/{{BadgeBase}}/discussions) ## Author **{{Author}}** ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. --- Made with ❤️ by {{Author}} '@ $content = $template -replace '\{\{ModuleName\}\}', $ModuleName ` -replace '\{\{Description\}\}', $Description ` -replace '\{\{BadgeBase\}\}', $badgeBase ` -replace '\{\{FunctionList\}\}', $functionList ` -replace '\{\{Author\}\}', $Author return $content } # Main function - defined after helper functions for cross-platform compatibility function New-PstReadme { <# .SYNOPSIS Generates README.md content based on complexity level. .DESCRIPTION Creates README.md documentation for PowerShell modules based on the specified complexity level. The generated documentation varies in comprehensiveness: - Basic: Title, Description, Installation, Usage - Standard: + Features, Examples, Parameters, Contributing - Advanced: + Badges, Architecture, Development Setup, Testing, CI/CD, Changelog .PARAMETER ModuleName The name of the module to generate documentation for. .PARAMETER Description Brief description of what the module does. .PARAMETER Complexity The complexity level: Basic, Standard, or Advanced. .PARAMETER Author Optional author name for the module. .PARAMETER ProjectUri Optional project URI (GitHub repository URL). .PARAMETER Functions Optional array of function names exported by the module. .PARAMETER OutputPath Optional path where the README file should be created. If not specified, returns the content as a string. .EXAMPLE New-PstReadme -ModuleName "MyModule" -Description "A useful module" -Complexity Basic Generates basic README content for MyModule. .EXAMPLE New-PstReadme -ModuleName "DataTools" -Complexity Advanced -OutputPath ".\docs\" Creates an Advanced README file with full documentation structure. .NOTES Version: 1.0 Author: numidia Creation Date: 2025-12-05 Purpose: Auto-generate README documentation based on complexity level #> [CmdletBinding(SupportsShouldProcess)] [OutputType([string])] param( [Parameter(Mandatory = $true)] [string]$ModuleName, [Parameter(Mandatory = $false)] [string]$Description = "A PowerShell module for automation and productivity.", [Parameter(Mandatory = $true)] [ValidateSet('Basic', 'Standard', 'Advanced')] [string]$Complexity, [Parameter(Mandatory = $false)] [string]$Author = $env:USERNAME, [Parameter(Mandatory = $false)] [string]$ProjectUri, [Parameter(Mandatory = $false)] [string[]]$Functions = @(), [Parameter(Mandatory = $false)] [string]$OutputPath ) begin { Write-Debug "Begin '$($MyInvocation.MyCommand.Name)' at '$(Get-Date)'" } process { try { # Generate content based on complexity $content = switch ($Complexity) { 'Basic' { Get-BasicReadmeContent -ModuleName $ModuleName -Description $Description } 'Standard' { Get-StandardReadmeContent -ModuleName $ModuleName -Description $Description -Author $Author -Functions $Functions } 'Advanced' { Get-AdvancedReadmeContent -ModuleName $ModuleName -Description $Description -Author $Author -ProjectUri $ProjectUri -Functions $Functions } } # Output to file if path specified if ($OutputPath) { $fileName = "README.md" $fullPath = Join-Path $OutputPath $fileName # Ensure directory exists $directory = Split-Path $fullPath -Parent if (-not (Test-Path $directory)) { if ($PSCmdlet.ShouldProcess($directory, "Create directory")) { New-Item -Path $directory -ItemType Directory -Force | Out-Null } } if ($PSCmdlet.ShouldProcess($fullPath, "Create README file")) { $content | Set-Content -Path $fullPath -Encoding UTF8 Write-Verbose "Created README file: $fullPath" } return $fullPath } return $content } catch { $PSCmdlet.ThrowTerminatingError($_) } } end { Write-Debug "End '$($MyInvocation.MyCommand.Name)' at '$(Get-Date)'" } } |