From 04a85dbe4f2118d4ed6df14b84515a27a605acdb Mon Sep 17 00:00:00 2001 From: Gilbert Sanchez Date: Fri, 24 Apr 2026 10:12:25 -0700 Subject: [PATCH 01/11] Migrate to Microsoft.PowerShell.PlatyPS and psake v5 - Replace Alt3.Docusaurus.Powershell + PlatyPS v0 with Microsoft.PowerShell.PlatyPS - Add scripts/New-PsakeDocusaurusHelp.ps1 to transform PlatyPS v2 markdown to Docusaurus MDX - Bump psake to 5.0.3; convert main tasks to v5 declarative hashtable syntax - Add -Quiet flag to build.ps1 for structured PsakeBuildResult output (reduces token usage) - Add 8 new command reference MDX files for psake v5 commands Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 6 +- build.ps1 | 7 +- docs/commands/BuildSetup.mdx | 106 +++++++++++ docs/commands/BuildTearDown.mdx | 130 ++++++++++++++ docs/commands/Clear-PsakeCache.mdx | 121 +++++++++++++ docs/commands/Execute.mdx | 204 +++++++++++++++++++++ docs/commands/Get-PsakeBuildPlan.mdx | 146 +++++++++++++++ docs/commands/Test-BuildEnvironment.mdx | 174 ++++++++++++++++++ docs/commands/Test-PsakeTask.mdx | 140 +++++++++++++++ docs/commands/Version.mdx | 95 ++++++++++ psakeFile.ps1 | 69 +++---- requirements.psd1 | 7 +- scripts/New-PsakeDocusaurusHelp.ps1 | 229 ++++++++++++++++++++++++ 13 files changed, 1393 insertions(+), 41 deletions(-) create mode 100644 docs/commands/BuildSetup.mdx create mode 100644 docs/commands/BuildTearDown.mdx create mode 100644 docs/commands/Clear-PsakeCache.mdx create mode 100644 docs/commands/Execute.mdx create mode 100644 docs/commands/Get-PsakeBuildPlan.mdx create mode 100644 docs/commands/Test-BuildEnvironment.mdx create mode 100644 docs/commands/Test-PsakeTask.mdx create mode 100644 docs/commands/Version.mdx create mode 100644 scripts/New-PsakeDocusaurusHelp.ps1 diff --git a/CLAUDE.md b/CLAUDE.md index 6174576..40f7ebe 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -33,6 +33,8 @@ The build system uses **PowerShell + psake** for orchestration, with Docusaurus/ .\build.ps1 -Help ``` +> **Token efficiency**: Always prefer `.\build.ps1 -Quiet -Task ` when running builds from Claude Code. The `-Quiet` flag suppresses verbose console output and returns a structured `PsakeBuildResult` object, which dramatically reduces token usage while still capturing success/failure. + **Important**: The `Server` task runs `bun run serve` which serves the production build. For local development with hot-reload, use: ```powershell .\build.ps1 -Task Init # Install dependencies first @@ -54,11 +56,11 @@ bun start # Then start dev server directly Command documentation is **auto-generated** from the psake PowerShell module: -- **Generator**: `New-DocusaurusHelp` from `Alt3.Docusaurus.Powershell` module +- **Generator**: `New-PsakeDocusaurusHelp` in `scripts/New-PsakeDocusaurusHelp.ps1`, powered by `Microsoft.PowerShell.PlatyPS` - **Source**: psake module help (from the main psake repository) - **Output**: `docs/commands/*.mdx` files - **Sidebar**: Auto-imported via `docs/commands/docusaurus.sidebar.js` -- **Configuration**: See `$docusaurusOptions` in `psakeFile.ps1:12-34` +- **Configuration**: See `$docusaurusOptions` in `psakeFile.ps1` **Never manually edit files in `docs/commands/`** - they will be overwritten. Edit the source help in the [psake repository](https://github.com/psake/psake) instead. diff --git a/build.ps1 b/build.ps1 index d49daa8..e6606af 100644 --- a/build.ps1 +++ b/build.ps1 @@ -21,6 +21,9 @@ param( [parameter(ParameterSetName = 'Help')] [switch]$Help, + # Suppress console output (returns structured PsakeBuildResult) + [switch]$Quiet, + # Optional properties to pass to psake [hashtable]$Properties, @@ -51,6 +54,6 @@ if ($PSCmdlet.ParameterSetName -eq 'Help') { Get-PSakeScriptTasks -BuildFile $psakeFile | Format-Table -Property Name, Description, Alias, DependsOn } else { - Invoke-Psake -BuildFile $psakeFile -TaskList $Task -NoLogo -Properties $Properties -Parameters $Parameters - exit ([int](-not $psake.build_success)) + $result = Invoke-Psake -BuildFile $psakeFile -TaskList $Task -NoLogo -Properties $Properties -Parameters $Parameters -Quiet:$Quiet + exit ([int](-not $result.Success)) } diff --git a/docs/commands/BuildSetup.mdx b/docs/commands/BuildSetup.mdx new file mode 100644 index 0000000..e764599 --- /dev/null +++ b/docs/commands/BuildSetup.mdx @@ -0,0 +1,106 @@ +--- +id: BuildSetup +title: BuildSetup +description: Help page for the PowerShell Psake "BuildSetup" command +keywords: + - PowerShell + - Psake + - Help + - Documentation +hide_title: false +hide_table_of_contents: false +custom_edit_url: null +--- + +:::info This page was generated +Contributions are welcome in [Psake-repo](https://github.com/psake/psake). +::: + +## SYNOPSIS + +Adds a scriptblock that will be executed once at the beginning of the build + +## SYNTAX + +```powershell +BuildSetup [-Setup] [-ProgressAction ] [] +``` + +## DESCRIPTION + +This function will accept a scriptblock that will be executed once at the +beginning of the build. + +## EXAMPLES + +### EXAMPLE 1 + +```powershell +Task default -Depends Test +Task Test -Depends Compile, Clean { +} +Task Compile -Depends Clean { +} +Task Clean { +} +BuildSetup { + "Running 'BuildSetup'" +} +``` + +The script above produces the following output: +Running 'BuildSetup' +Executing task, Clean... +Executing task, Compile... +Executing task, Test... +Build Succeeded + +## PARAMETERS + +### -Setup + +A scriptblock to execute + +```yaml +Type: ScriptBlock +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ProgressAction + +\{\{ Fill ProgressAction Description \}\} + +```yaml +Type: ActionPreference +Parameter Sets: (All) +Aliases: proga + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES + +## RELATED LINKS + +## VERSION + +*This page was generated using comment-based help in [Psake 5.0.2](https://github.com/psake/psake).* diff --git a/docs/commands/BuildTearDown.mdx b/docs/commands/BuildTearDown.mdx new file mode 100644 index 0000000..2167bbf --- /dev/null +++ b/docs/commands/BuildTearDown.mdx @@ -0,0 +1,130 @@ +--- +id: BuildTearDown +title: BuildTearDown +description: Help page for the PowerShell Psake "BuildTearDown" command +keywords: + - PowerShell + - Psake + - Help + - Documentation +hide_title: false +hide_table_of_contents: false +custom_edit_url: null +--- + +:::info This page was generated +Contributions are welcome in [Psake-repo](https://github.com/psake/psake). +::: + +## SYNOPSIS + +Adds a scriptblock that will be executed once at the end of the build + +## SYNTAX + +```powershell +BuildTearDown [-Setup] [-ProgressAction ] [] +``` + +## DESCRIPTION + +This function will accept a scriptblock that will be executed once at the +end of the build, regardless of success or failure + +## EXAMPLES + +### EXAMPLE 1 + +```powershell +Task default -Depends Test +Task Test -Depends Compile, Clean { +} +Task Compile -Depends Clean { +} +Task Clean { +} +BuildTearDown { + "Running 'BuildTearDown'" +} +``` + +The script above produces the following output: +Executing task, Clean... +Executing task, Compile... +Executing task, Test... +Running 'BuildTearDown' +Build Succeeded + +### EXAMPLE 2 + +```powershell +Task default -Depends Test +Task Test -Depends Compile, Clean { + throw "forced error" +} +Task Compile -Depends Clean { +} +Task Clean { +} +BuildTearDown { + "Running 'BuildTearDown'" +} +``` + +The script above produces the following output: +Executing task, Clean... +Executing task, Compile... +Executing task, Test... +Running 'BuildTearDown' +forced error +At line:x char:x ... + +## PARAMETERS + +### -Setup + +A scriptblock to execute + +```yaml +Type: ScriptBlock +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ProgressAction + +\{\{ Fill ProgressAction Description \}\} + +```yaml +Type: ActionPreference +Parameter Sets: (All) +Aliases: proga + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES + +## RELATED LINKS + +## VERSION + +*This page was generated using comment-based help in [Psake 5.0.2](https://github.com/psake/psake).* diff --git a/docs/commands/Clear-PsakeCache.mdx b/docs/commands/Clear-PsakeCache.mdx new file mode 100644 index 0000000..7237c0c --- /dev/null +++ b/docs/commands/Clear-PsakeCache.mdx @@ -0,0 +1,121 @@ +--- +id: Clear-PsakeCache +title: Clear-PsakeCache +description: Help page for the PowerShell Psake "Clear-PsakeCache" command +keywords: + - PowerShell + - Psake + - Help + - Documentation +hide_title: false +hide_table_of_contents: false +custom_edit_url: null +--- + +:::info This page was generated +Contributions are welcome in [Psake-repo](https://github.com/psake/psake). +::: + +## SYNOPSIS + +Clears the psake build cache. + +## SYNTAX + +```powershell +Clear-PsakeCache [[-Path] ] [[-TaskName] ] [-ProgressAction ] + [] +``` + +## DESCRIPTION + +Removes cached task state from the .psake/cache/ directory. +This forces all tasks to re-execute on the next build. + +## EXAMPLES + +### EXAMPLE 1 + +```powershell +Clear-PsakeCache +``` + +Clears all cached task state in the current directory. + +### EXAMPLE 2 + +```powershell +Clear-PsakeCache -TaskName 'Build' +``` + +Clears cached state for the 'Build' task only. + +## PARAMETERS + +### -Path + +The directory containing the .psake/cache/ folder. +Defaults to the current +directory. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 1 +Default value: . +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -TaskName + +Optional: clear cache for a specific task only. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ProgressAction + +\{\{ Fill ProgressAction Description \}\} + +```yaml +Type: ActionPreference +Parameter Sets: (All) +Aliases: proga + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES + +## RELATED LINKS + +[Invoke-psake](Invoke-psake.mdx) + +## VERSION + +*This page was generated using comment-based help in [Psake 5.0.2](https://github.com/psake/psake).* diff --git a/docs/commands/Execute.mdx b/docs/commands/Execute.mdx new file mode 100644 index 0000000..83d07db --- /dev/null +++ b/docs/commands/Execute.mdx @@ -0,0 +1,204 @@ +--- +id: Execute +title: Execute +description: Help page for the PowerShell Psake "Execute" command +keywords: + - PowerShell + - Psake + - Help + - Documentation +hide_title: false +hide_table_of_contents: false +custom_edit_url: null +--- + +:::info This page was generated +Contributions are welcome in [Psake-repo](https://github.com/psake/psake). +::: + +## SYNOPSIS + +Helper function for executing command-line programs. + +## SYNTAX + +```powershell +Execute [-Cmd] [[-ErrorMessage] ] [[-MaxRetries] ] + [[-RetryTriggerErrorPattern] ] [[-WorkingDirectory] ] [-NewProcess] + [[-TimeoutSeconds] ] [-ProgressAction ] [] +``` + +## DESCRIPTION + +This is a helper function that runs a scriptblock and checks the PS variable +$lastexitcode to see if an error occured. + +If an error is detected then an exception is thrown. +This function allows you to run command-line programs without having to +explicitly check the $lastexitcode variable. + +## EXAMPLES + +### EXAMPLE 1 + +```powershell +Execute { svn info $repository_trunk } "Error executing SVN. Please verify SVN command-line client is installed" +``` + +This example calls the svn command-line client. + +## PARAMETERS + +### -Cmd + +The scriptblock to execute. +This scriptblock will typically contain the +command-line invocation. + +```yaml +Type: ScriptBlock +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ErrorMessage + +The error message to display if the external command returned a non-zero +exit code. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 2 +Default value: ($msgs.error_bad_command -f $Cmd.ToString().Trim()) +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -MaxRetries + +The maximum number of times to retry the command before failing. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: 3 +Default value: 0 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -RetryTriggerErrorPattern + +If the external command raises an exception, match the exception against +this regex to determine if the command can be retried. +If a match is found, +the command will be retried provided [MaxRetries] has not been reached. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 4 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WorkingDirectory + +The working directory to set before running the external command. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: wd + +Required: False +Position: 5 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -NewProcess + +If set, the command will be executed in a new process. +This can be used to +isolate the command's environment from the current process. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -TimeoutSeconds + +If set, the command will be terminated if it runs longer than this number of +seconds. +Defaults to 300 seconds (5 minutes). + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: 6 +Default value: 300 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ProgressAction + +\{\{ Fill ProgressAction Description \}\} + +```yaml +Type: ActionPreference +Parameter Sets: (All) +Aliases: proga + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES + +## RELATED LINKS + +## VERSION + +*This page was generated using comment-based help in [Psake 5.0.2](https://github.com/psake/psake).* diff --git a/docs/commands/Get-PsakeBuildPlan.mdx b/docs/commands/Get-PsakeBuildPlan.mdx new file mode 100644 index 0000000..bca641c --- /dev/null +++ b/docs/commands/Get-PsakeBuildPlan.mdx @@ -0,0 +1,146 @@ +--- +id: Get-PsakeBuildPlan +title: Get-PsakeBuildPlan +description: Help page for the PowerShell Psake "Get-PsakeBuildPlan" command +keywords: + - PowerShell + - Psake + - Help + - Documentation +hide_title: false +hide_table_of_contents: false +custom_edit_url: null +--- + +:::info This page was generated +Contributions are welcome in [Psake-repo](https://github.com/psake/psake). +::: + +## SYNOPSIS + +Compiles a build file and returns the build plan without executing any tasks. + +## SYNTAX + +```powershell +Get-PsakeBuildPlan [[-BuildFile] ] [[-TaskList] ] [-ProgressAction ] + [] +``` + +## DESCRIPTION + +This is the primary testability API for psake v5. +It loads a build file, +validates the dependency graph, and returns a PsakeBuildPlan object that +can be inspected in tests. + +This function always returns a [PsakeBuildPlan]. +If the build file cannot +be loaded or the dependency graph is invalid, an invalid plan is returned +with IsValid = $false and ValidationErrors populated. + +The returned plan can be piped into Invoke-Psake for execution. +Note that +when piping, the build file is re-loaded during the execution phase to +resolve properties, setup, and teardown blocks. + +## EXAMPLES + +### EXAMPLE 1 + +```powershell +$plan = Get-PsakeBuildPlan -BuildFile './psakefile.ps1' +$plan.Tasks | Should -HaveCount 4 +$plan.ExecutionOrder | Should -Be @('Clean', 'Compile', 'Test', 'Default') +``` + +This example compiles the build file and asserts that there are 4 tasks and +that the execution order is correct. + +### EXAMPLE 2 + +```powershell +$plan = Get-PsakeBuildPlan +$plan.TaskMap['build'].DependsOn | Should -Contain 'Clean' +$plan.IsValid | Should -BeTrue +``` + +This example compiles the default build file and asserts that the 'build' +task depends on the 'Clean' task and that the plan is valid. + +### EXAMPLE 3 + +```powershell +Get-PsakeBuildPlan -BuildFile './psakefile.ps1' | Invoke-Psake +``` + +Compiles the build plan and pipes it into Invoke-Psake for execution. +Note: the build file is re-loaded during the execution phase. + +## PARAMETERS + +### -BuildFile + +The path to the psake build script. +Defaults to 'psakefile.ps1'. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -TaskList + +A list of task names to include in the plan. +Defaults to 'default'. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: 2 +Default value: @('default') +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ProgressAction + +\{\{ Fill ProgressAction Description \}\} + +```yaml +Type: ActionPreference +Parameter Sets: (All) +Aliases: proga + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES + +## RELATED LINKS + +## VERSION + +*This page was generated using comment-based help in [Psake 5.0.2](https://github.com/psake/psake).* diff --git a/docs/commands/Test-BuildEnvironment.mdx b/docs/commands/Test-BuildEnvironment.mdx new file mode 100644 index 0000000..f30e2c1 --- /dev/null +++ b/docs/commands/Test-BuildEnvironment.mdx @@ -0,0 +1,174 @@ +--- +id: Test-BuildEnvironment +title: Test-BuildEnvironment +description: Help page for the PowerShell Psake "Test-BuildEnvironment" command +keywords: + - PowerShell + - Psake + - Help + - Documentation +hide_title: false +hide_table_of_contents: false +custom_edit_url: null +--- + +:::info This page was generated +Contributions are welcome in [Psake-repo](https://github.com/psake/psake). +::: + +## SYNOPSIS + +Tests whether the .NET framework required by a build is available on the +current machine. + +## SYNTAX + +### Framework (Default) + +```powershell +Test-BuildEnvironment [[-Framework] ] [-ProgressAction ] [] +``` + +### BuildFile + +```powershell +Test-BuildEnvironment -BuildFile [-ProgressAction ] [] +``` + +## DESCRIPTION + +Resolves the MSBuild and .NET runtime directories for the specified +framework version and checks that every required directory exists. +Returns $true if the environment is ready, $false otherwise. + +The framework to check is determined in order of precedence: + 1. +The -Framework parameter, if supplied. + 2. +The framework declared in -BuildFile, if supplied. + 3. +The active psake build context (if one is on the stack). + 4. +The psake default framework (4.7.2). + +This is useful in Pester specs to skip tests that require a framework +toolchain that is not installed: + + It 'compiles with MSBuild 4.8' \{ + if (-not (Test-BuildEnvironment -Framework '4.8')) \{ + Set-ItResult -Skipped -Because 'Framework 4.8 not available' + \} + # ... +rest of test + \} + + It 'uses the project framework' \{ + if (-not (Test-BuildEnvironment -BuildFile './psakefile.ps1')) \{ + Set-ItResult -Skipped -Because 'Required framework not available' + \} + # ... +rest of test + \} + +## EXAMPLES + +### EXAMPLE 1 + +```powershell +Test-BuildEnvironment -Framework '4.8' +``` + +Returns $true when MSBuild 17.0 or 16.0 and the v4.0.30319 runtime +directory are both present. + +### EXAMPLE 2 + +```powershell +Test-BuildEnvironment -BuildFile './psakefile.ps1' +``` + +Loads the build file, reads its Framework setting, and returns $true if +that framework is installed. + +### EXAMPLE 3 + +```powershell +if (-not (Test-BuildEnvironment)) { + Write-Warning "Build environment not ready for current framework" +} +``` + +Tests the framework configured in the active psake context. + +## PARAMETERS + +### -Framework + +The .NET framework version string to test (e.g. +'4.8', '3.5', '4.7.2x64'). +Takes precedence over -BuildFile and the active context. + +```yaml +Type: String +Parameter Sets: Framework +Aliases: + +Required: False +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -BuildFile + +Path to a psake build script. +The framework declared in that file is read +and tested. +Ignored when -Framework is also supplied. + +```yaml +Type: String +Parameter Sets: BuildFile +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ProgressAction + +\{\{ Fill ProgressAction Description \}\} + +```yaml +Type: ActionPreference +Parameter Sets: (All) +Aliases: proga + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +### [bool] + +## NOTES + +## RELATED LINKS + +## VERSION + +*This page was generated using comment-based help in [Psake 5.0.2](https://github.com/psake/psake).* diff --git a/docs/commands/Test-PsakeTask.mdx b/docs/commands/Test-PsakeTask.mdx new file mode 100644 index 0000000..91085a2 --- /dev/null +++ b/docs/commands/Test-PsakeTask.mdx @@ -0,0 +1,140 @@ +--- +id: Test-PsakeTask +title: Test-PsakeTask +description: Help page for the PowerShell Psake "Test-PsakeTask" command +keywords: + - PowerShell + - Psake + - Help + - Documentation +hide_title: false +hide_table_of_contents: false +custom_edit_url: null +--- + +:::info This page was generated +Contributions are welcome in [Psake-repo](https://github.com/psake/psake). +::: + +## SYNOPSIS + +Runs a single task's Action in isolation, without triggering dependencies. + +## SYNTAX + +```powershell +Test-PsakeTask [[-BuildFile] ] [-TaskName] [[-Variables] ] + [-ProgressAction ] [] +``` + +## DESCRIPTION + +Compiles the build file, finds the specified task, and executes only its +Action scriptblock with the provided variables. +Dependencies are NOT +executed.This enables unit-testing individual tasks. + +## EXAMPLES + +### EXAMPLE 1 + +```powershell +$result = Test-PsakeTask -BuildFile './psakefile.ps1' -TaskName 'Build' -Variables @{ + Configuration = 'Debug' + OutputDir = './test-output' +} +$result.Success | Should -BeTrue +``` + +This example runs the 'Build' task from 'psakefile.ps1' with two variables +injected into the task's scope. +The result object contains details about the +execution, including success status, duration, and any error messages. + +## PARAMETERS + +### -BuildFile + +The path to the psake build script. +Defaults to 'psakefile.ps1'. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -TaskName + +The name of the task to execute. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Variables + +A hashtable of variables to inject into the task's execution scope. + +```yaml +Type: Hashtable +Parameter Sets: (All) +Aliases: + +Required: False +Position: 3 +Default value: @{} +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ProgressAction + +\{\{ Fill ProgressAction Description \}\} + +```yaml +Type: ActionPreference +Parameter Sets: (All) +Aliases: proga + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES + +This function is intended for testing purposes and does not execute task +dependencies or pre/post actions. +It directly invokes the specified task's +Action scriptblock in isolation. + +## RELATED LINKS + +## VERSION + +*This page was generated using comment-based help in [Psake 5.0.2](https://github.com/psake/psake).* diff --git a/docs/commands/Version.mdx b/docs/commands/Version.mdx new file mode 100644 index 0000000..4844e5c --- /dev/null +++ b/docs/commands/Version.mdx @@ -0,0 +1,95 @@ +--- +id: Version +title: Version +description: Help page for the PowerShell Psake "Version" command +keywords: + - PowerShell + - Psake + - Help + - Documentation +hide_title: false +hide_table_of_contents: false +custom_edit_url: null +--- + +:::info This page was generated +Contributions are welcome in [Psake-repo](https://github.com/psake/psake). +::: + +## SYNOPSIS + +Declares the required psake version for the build script. + +## SYNTAX + +```powershell +Version [-RequiredVersion] [-ProgressAction ] [] +``` + +## DESCRIPTION + +Use this function at the top of a psake build script to declare which +major version of psake the script requires. +The compile phase will validate +that the running psake version matches. + +## EXAMPLES + +### EXAMPLE 1 + +```powershell +Version 5 +``` + +Declares that this build script requires psake v5. + +## PARAMETERS + +### -RequiredVersion + +The major version number required (e.g. +5). + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: 0 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ProgressAction + +\{\{ Fill ProgressAction Description \}\} + +```yaml +Type: ActionPreference +Parameter Sets: (All) +Aliases: proga + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES + +## RELATED LINKS + +## VERSION + +*This page was generated using comment-based help in [Psake 5.0.2](https://github.com/psake/psake).* diff --git a/psakeFile.ps1 b/psakeFile.ps1 index f12a766..a3f3f2a 100644 --- a/psakeFile.ps1 +++ b/psakeFile.ps1 @@ -1,7 +1,8 @@ #require -Version 7 +Version 5 + $ErrorView = 'Detailed' -Version 5 Properties { $script:OutputPath = $null $script:OutputFormat = 'Nunit' @@ -33,6 +34,7 @@ Contributions are welcome in [Psake-repo](https://github.com/psake/psake). ## VERSION *This page was generated using comment-based help in [Psake $($psakeVersion)](https://github.com/psake/psake).* "@ + HelpVersion = "$($script:psakeVersion)" } $script:docsOutputFolder = Join-Path -Path $docusaurusOptions.DocsFolder -ChildPath $docusaurusOptions.Sidebar | Join-Path -ChildPath "*.*" } @@ -45,31 +47,42 @@ FormatTaskName { Task Default -Depends Build -Task Init -Description "Initial action to setup the further action." -Action { - Exec { bun install } +Task 'Init' @{ + Description = 'Install Node.js dependencies.' + Inputs = @('package.json', 'bun.lock') + Outputs = 'node_modules/.cache' + Action = { exec { bun install } } } -Task Build -Depends Init, GenerateCommandReference, FrontMatterCMSSync { - Exec { bun run build } +Task 'Build' @{ + Description = 'Full production site build.' + DependsOn = @('Init', 'GenerateCommandReference', 'FrontMatterCMSSync') + Action = { exec { bun run build } } } -Task Server -Depends Build -Description "Run the docusaurus server." { - Exec { bun run serve } +Task 'Server' @{ + Description = 'Serve the production build locally.' + DependsOn = 'Build' + Action = { exec { bun run serve } } } -Task Test { - $configuration = New-PesterConfiguration - $configuration.Output.Verbosity = 'Detailed' - $configuration.Run.PassThru = $true - $configuration.Run.Path = "$PSScriptRoot\tests" - - try { - $testResult = Invoke-Pester -Configuration $configuration -Verbose - } finally { - } +Task 'Test' @{ + Description = 'Run Pester tests to validate sidebar links.' + Action = { + Import-Module Pester -MinimumVersion '5.0' -Force + $configuration = New-PesterConfiguration + $configuration.Output.Verbosity = 'Detailed' + $configuration.Run.PassThru = $true + $configuration.Run.Path = "$PSScriptRoot\tests" + + try { + $testResult = Invoke-Pester -Configuration $configuration -Verbose + } finally { + } - if ($testResult.FailedCount -gt 0) { - throw 'One or more Pester tests failed' + if ($testResult.FailedCount -gt 0) { + throw 'One or more Pester tests failed' + } } } @@ -85,9 +98,8 @@ Task Test { } #region Command Reference Generation Tasks -# Copied from the amazing Pester team! https://github.com/pester/docs/blob/main/generate-command-reference.ps1 $taskSplat = @{ - description = "Use Alt3.Docusaurus.Powershell module to generate our reference docs." + description = "Use Microsoft.PowerShell.PlatyPS to generate command reference docs." depends = 'GenerateCommandReference-Gen' } Task -Name 'GenerateCommandReference' @taskSplat @@ -100,17 +112,10 @@ Task -Name 'GenerateCommandReference-Clean' -Action { } Task -Name "GenerateCommandReference-Gen" -Depends 'GenerateCommandReference-Clean' { - Write-Host "Generating new MDX files" -ForegroundColor Magenta - New-DocusaurusHelp @docusaurusOptions - - # Fix the links - Get-ChildItem $script:docsOutputFolder | ForEach-Object { - $path = $_.FullName - Write-Host "Fixing relative links for: $path" - (Get-Content $path) | ForEach-Object { - $_ -replace "\[(.+)\]\(\)", '[$1]($1.mdx)' - } | Set-Content $path - } + Write-Host "Generating new MDX files using Microsoft.PowerShell.PlatyPS" -ForegroundColor Magenta + . "$PSScriptRoot\scripts\New-PsakeDocusaurusHelp.ps1" + Import-Module Microsoft.PowerShell.PlatyPS -Force + New-PsakeDocusaurusHelp @docusaurusOptions } #endregion Command Reference Generation Tasks diff --git a/requirements.psd1 b/requirements.psd1 index ab180c2..f1c3d07 100644 --- a/requirements.psd1 +++ b/requirements.psd1 @@ -11,11 +11,8 @@ 'psake' = @{ Version = '5.0.3' } - 'PlatyPS' = @{ - Version = '0.14.2' - } - 'Alt3.Docusaurus.Powershell' = @{ - Version = '1.0.36' + 'Microsoft.PowerShell.PlatyPS' = @{ + Version = 'latest' } 'Yayaml' = @{ Version = '0.6.0' diff --git a/scripts/New-PsakeDocusaurusHelp.ps1 b/scripts/New-PsakeDocusaurusHelp.ps1 new file mode 100644 index 0000000..3282921 --- /dev/null +++ b/scripts/New-PsakeDocusaurusHelp.ps1 @@ -0,0 +1,229 @@ +function New-PsakeDocusaurusHelp { + [CmdletBinding()] + param( + [Parameter(Mandatory)] [string] $Module, + [Parameter(Mandatory)] [string] $DocsFolder, + [Parameter(Mandatory)] [string] $SideBar, + [string] $EditUrl = 'null', + [string[]] $Exclude = @(), + [string] $MetaDescription = 'Help page for the PowerShell %1 command', + [string[]] $MetaKeywords = @('PowerShell', 'Help', 'Documentation'), + [string] $PrependMarkdown = '', + [string] $AppendMarkdown = '', + [string] $HelpVersion = '' + ) + + Import-Module $Module -Force + + $tempDir = Join-Path ([System.IO.Path]::GetTempPath()) "platyps_$(Get-Random)" + New-Item -ItemType Directory -Path $tempDir | Out-Null + + try { + New-MarkdownCommandHelp -ModuleInfo (Get-Module $Module) -OutputFolder $tempDir -Force | Out-Null + + $moduleSubDir = Join-Path $tempDir $Module + $mdFiles = Get-ChildItem -Path $moduleSubDir -Filter '*.md' | + Where-Object { $_.BaseName -notin $Exclude } | + Sort-Object BaseName + + $outputFolder = Join-Path $DocsFolder $SideBar + $allCommandNames = $mdFiles | Select-Object -ExpandProperty BaseName + $sidebarItems = [System.Collections.Generic.List[string]]::new() + + foreach ($mdFile in $mdFiles) { + $commandName = $mdFile.BaseName + $mdxContent = ConvertTo-DocusaurusMdx ` + -SourceFile $mdFile ` + -CommandName $commandName ` + -MetaDescription $MetaDescription ` + -MetaKeywords $MetaKeywords ` + -EditUrl $EditUrl ` + -PrependMarkdown $PrependMarkdown ` + -AppendMarkdown $AppendMarkdown ` + -AllCommandNames $allCommandNames + + $outputPath = Join-Path $outputFolder "$commandName.mdx" + Set-Content -Path $outputPath -Value $mdxContent -Encoding UTF8 -NoNewline + Write-Host " Generated: $commandName.mdx" + + $sidebarItems.Add("'$SideBar/$commandName'") + } + + $sidebarEntries = ($sidebarItems | ForEach-Object { " $_" }) -join ",`n" + $sidebarContent = @" +/** + * Import this file in your Docusaurus ``sidebars.js`` file. + * + * Auto-generated by New-PsakeDocusaurusHelp using Microsoft.PowerShell.PlatyPS. + */ + +module.exports = [ +$sidebarEntries +]; +"@ + $sidebarPath = Join-Path $outputFolder 'docusaurus.sidebar.js' + Set-Content -Path $sidebarPath -Value $sidebarContent -Encoding UTF8 -NoNewline + Write-Host " Generated: docusaurus.sidebar.js ($($sidebarItems.Count) commands)" + } + finally { + Remove-Item -Path $tempDir -Recurse -Force -ErrorAction SilentlyContinue + } +} + +function ConvertTo-DocusaurusMdx { + param( + [System.IO.FileInfo] $SourceFile, + [string] $CommandName, + [string] $MetaDescription, + [string[]] $MetaKeywords, + [string] $EditUrl, + [string] $PrependMarkdown, + [string] $AppendMarkdown, + [string[]] $AllCommandNames + ) + + $raw = Get-Content -Path $SourceFile.FullName -Raw + + # Strip PlatyPS v2 frontmatter block + $body = $raw -replace '(?s)^---.*?---\s*', '' + + # Strip the H1 title line PlatyPS emits + $body = $body -replace '(?m)^# .+\r?\n', '' + + # Convert markdown parameter tables to yaml fenced blocks + $body = Convert-ParameterTablesToYamlFences -Body $body + + # Fix RELATED LINKS: [Name]() -> [Name](Name.mdx) for known commands, strip unknown + foreach ($cmd in $AllCommandNames) { + $escaped = [regex]::Escape($cmd) + $body = $body -replace "\[$escaped\]\(\)", "[$cmd]($cmd.mdx)" + } + $body = $body -replace '\[([^\]]+)\]\(\)', '$1' + + # Escape curly braces outside code fences (required for MDX/JSX compatibility) + $body = Escape-CurlyBracesOutsideCodeFences -Body $body + + # Build Docusaurus frontmatter + $description = $MetaDescription -replace '%1', $CommandName + $keywordsYaml = ($MetaKeywords | ForEach-Object { " - $_" }) -join "`n" + $customEditUrl = if ($EditUrl -eq 'null') { 'null' } else { "$EditUrl/$CommandName.ps1" } + + $frontmatter = @" +--- +id: $CommandName +title: $CommandName +description: $description +keywords: +$keywordsYaml +hide_title: false +hide_table_of_contents: false +custom_edit_url: $customEditUrl +--- +"@ + + $parts = [System.Collections.Generic.List[string]]::new() + $parts.Add($frontmatter) + if ($PrependMarkdown) { $parts.Add($PrependMarkdown.Trim()) } + $parts.Add($body.Trim()) + if ($AppendMarkdown) { $parts.Add($AppendMarkdown.Trim()) } + + return ($parts -join "`n`n") + "`n" +} + +function Convert-ParameterTablesToYamlFences { + param([string] $Body) + + # Match each ### -ParameterName block through to the next ### - or end of PARAMETERS section + $result = [System.Text.RegularExpressions.Regex]::Replace( + $Body, + '(?ms)(### -\w[^\r\n]*\r?\n)(.*?)(?=### -|\z)', + { + param($match) + $header = $match.Groups[1].Value + $content = $match.Groups[2].Value + + # Extract description text (everything before the first table row) + $descText = ($content -split '(?m)^\|')[0].TrimEnd() + + # Helper: extract a value from a markdown table row by property name + function Get-TableValue([string]$text, [string]$prop) { + if ($text -match "(?m)^\|\s*$([regex]::Escape($prop))\s*\|\s*([^|]+)\|") { + return $matches[1].Trim() + } + return $null + } + + $type = Get-TableValue $content 'Type:' + $mandatory = Get-TableValue $content 'Mandatory:' + $position = Get-TableValue $content 'Position:' + $default = Get-TableValue $content 'Default value:' + $pipeline = Get-TableValue $content 'Value from pipeline:' + $wildcard = Get-TableValue $content 'Supports wildcards:' + $aliases = Get-TableValue $content 'Aliases:' + + # Strip System. namespace prefix from types + if ($type) { $type = $type -replace '^System\.', '' } else { $type = 'None' } + + $required = if ($mandatory -eq 'True') { 'True' } else { 'False' } + + # v2 position is 0-based; v1 (target) is 1-based + if ($position -and $position -match '^\d+$') { + $position = [int]$position + 1 + } elseif (-not $position) { + $position = 'Named' + } + + if (-not $default) { $default = 'None' } + if (-not $pipeline) { $pipeline = 'False' } + if (-not $wildcard) { $wildcard = 'False' } + if (-not $aliases) { $aliases = '' } + + # Detect parameter sets - look for "Parameter sets" section in the content + $paramSets = '(All)' + if ($content -match '(?ms)Parameter sets\s*\r?\n\|[^\r\n]+\r?\n\|[^\r\n]+\r?\n\|\s*([^|]+)\|') { + $paramSets = $matches[1].Trim() + } + + $yamlFence = @" + +``````yaml +Type: $type +Parameter Sets: $paramSets +Aliases: $aliases + +Required: $required +Position: $position +Default value: $default +Accept pipeline input: $pipeline +Accept wildcard characters: $wildcard +`````` + +"@ + return $header + $descText + $yamlFence + } + ) + + return $result +} + +function Escape-CurlyBracesOutsideCodeFences { + param([string] $Body) + + # Split on fenced code blocks (``` delimiters), alternating outside/inside + $segments = [System.Text.RegularExpressions.Regex]::Split( + $Body, + '((?ms)^```[^\r\n]*\r?\n.*?^```\r?\n?)' + ) + + $result = for ($i = 0; $i -lt $segments.Count; $i++) { + if ($i % 2 -eq 0) { + # Outside a code fence — escape curly braces + $segments[$i] -replace '\{', '\{' -replace '\}', '\}' + } else { + # Inside a code fence — pass through unchanged + $segments[$i] + } + } + + return $result -join '' +} From dea0286e4ba7957f6d21b205a226a3160a8e2531 Mon Sep 17 00:00:00 2001 From: Gilbert Sanchez Date: Fri, 24 Apr 2026 12:07:55 -0700 Subject: [PATCH 02/11] Add all 20 psake v5 commands to sidebar The sidebar was generated by the old Alt3 module and only listed 12 commands. The 8 new v5 command MDX files are now included. Co-Authored-By: Claude Sonnet 4.6 --- docs/commands/docusaurus.sidebar.js | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/commands/docusaurus.sidebar.js b/docs/commands/docusaurus.sidebar.js index 53b0a0f..06c324a 100644 --- a/docs/commands/docusaurus.sidebar.js +++ b/docs/commands/docusaurus.sidebar.js @@ -1,18 +1,19 @@ /** * Import this file in your Docusaurus `sidebars.js` file. * - * Auto-generated by Alt3.Docusaurus.Powershell 1.0.36. - * - * Copyright (c) 2019-present, ALT3 B.V. - * - * Licensed under the MIT license. + * Auto-generated by New-PsakeDocusaurusHelp using Microsoft.PowerShell.PlatyPS. */ module.exports = [ 'commands/Assert', + 'commands/BuildSetup', + 'commands/BuildTearDown', + 'commands/Clear-PsakeCache', 'commands/Exec', + 'commands/Execute', 'commands/FormatTaskName', 'commands/Framework', + 'commands/Get-PsakeBuildPlan', 'commands/Get-PSakeScriptTasks', 'commands/Include', 'commands/Invoke-psake', @@ -20,5 +21,8 @@ module.exports = [ 'commands/Properties', 'commands/Task', 'commands/TaskSetup', - 'commands/TaskTearDown' + 'commands/TaskTearDown', + 'commands/Test-BuildEnvironment', + 'commands/Test-PsakeTask', + 'commands/Version', ]; From d0cb5793576f07209d18afeed1e9fd84ca5863d0 Mon Sep 17 00:00:00 2001 From: Gilbert Sanchez Date: Fri, 24 Apr 2026 12:41:05 -0700 Subject: [PATCH 03/11] Add PowerShellBuild command reference generation - Add PowerShellBuild module to requirements.psd1 - Add $psbOptions/$psbVersion/$psbOutputFolder to Properties block - Add GenerateCommandReferencePSB task set (Clean, Gen) - Wire GenerateCommandReferencePSB into Build task DependsOn - Add docs/psb-commands/ placeholder sidebar (empty until task runs) - Import psbCommands in sidebars.ts with conditional category in powershellBuildSidebar Co-Authored-By: Claude Sonnet 4.6 --- docs/psb-commands/docusaurus.sidebar.js | 8 ++++ psakeFile.ps1 | 57 ++++++++++++++++++++++++- requirements.psd1 | 3 ++ sidebars.ts | 6 +++ 4 files changed, 73 insertions(+), 1 deletion(-) create mode 100644 docs/psb-commands/docusaurus.sidebar.js diff --git a/docs/psb-commands/docusaurus.sidebar.js b/docs/psb-commands/docusaurus.sidebar.js new file mode 100644 index 0000000..25f6d15 --- /dev/null +++ b/docs/psb-commands/docusaurus.sidebar.js @@ -0,0 +1,8 @@ +/** + * Import this file in your Docusaurus `sidebars.js` file. + * + * Auto-generated by New-PsakeDocusaurusHelp using Microsoft.PowerShell.PlatyPS. + * Run .\build.ps1 -Task GenerateCommandReferencePSB to populate. + */ + +module.exports = []; diff --git a/psakeFile.ps1 b/psakeFile.ps1 index a3f3f2a..89f5aaf 100644 --- a/psakeFile.ps1 +++ b/psakeFile.ps1 @@ -37,6 +37,37 @@ Contributions are welcome in [Psake-repo](https://github.com/psake/psake). HelpVersion = "$($script:psakeVersion)" } $script:docsOutputFolder = Join-Path -Path $docusaurusOptions.DocsFolder -ChildPath $docusaurusOptions.Sidebar | Join-Path -ChildPath "*.*" + + # ----------------------------------------------------------------------------- + # PowerShellBuild command reference options + # ----------------------------------------------------------------------------- + + $script:psbVersion = (Get-Module PowerShellBuild -ListAvailable | Sort-Object Version -Descending | Select-Object -First 1).Version + $script:psbOptions = @{ + Module = "PowerShellBuild" + DocsFolder = "./docs" + SideBar = "psb-commands" + EditUrl = "null" + Exclude = @() + MetaDescription = 'Help page for the PowerShellBuild "%1" command' + MetaKeywords = @( + "PowerShell" + "PowerShellBuild" + "Help" + "Documentation" + ) + PrependMarkdown = @" +:::info This page was generated +Contributions are welcome in [PowerShellBuild-repo](https://github.com/psake/PowerShellBuild). +::: +"@ + AppendMarkdown = @" +## VERSION +*This page was generated using comment-based help in [PowerShellBuild $($psbVersion)](https://github.com/psake/PowerShellBuild).* +"@ + HelpVersion = "$($script:psbVersion)" + } + $script:psbOutputFolder = Join-Path -Path $psbOptions.DocsFolder -ChildPath $psbOptions.Sidebar | Join-Path -ChildPath "*.*" } FormatTaskName { @@ -56,7 +87,7 @@ Task 'Init' @{ Task 'Build' @{ Description = 'Full production site build.' - DependsOn = @('Init', 'GenerateCommandReference', 'FrontMatterCMSSync') + DependsOn = @('Init', 'GenerateCommandReference', 'GenerateCommandReferencePSB', 'FrontMatterCMSSync') Action = { exec { bun run build } } } @@ -119,6 +150,30 @@ Task -Name "GenerateCommandReference-Gen" -Depends 'GenerateCommandReference-Cle } #endregion Command Reference Generation Tasks +#region PSB Command Reference Generation Tasks +$taskSplat = @{ + description = "Use Microsoft.PowerShell.PlatyPS to generate PowerShellBuild command reference docs." + depends = 'GenerateCommandReferencePSB-Gen' +} +Task -Name 'GenerateCommandReferencePSB' @taskSplat + +Task -Name 'GenerateCommandReferencePSB-Clean' -Action { + Write-Host "Removing existing PSB MDX files" -ForegroundColor Magenta + if (Test-Path -Path $script:psbOutputFolder) { + Remove-Item -Path $script:psbOutputFolder + } +} + +Task -Name "GenerateCommandReferencePSB-Gen" -Depends 'GenerateCommandReferencePSB-Clean' { + Write-Host "Generating new PSB MDX files using Microsoft.PowerShell.PlatyPS" -ForegroundColor Magenta + New-Item -ItemType Directory -Path (Join-Path $psbOptions.DocsFolder $psbOptions.SideBar) -Force | Out-Null + . "$PSScriptRoot\scripts\New-PsakeDocusaurusHelp.ps1" + Import-Module Microsoft.PowerShell.PlatyPS -Force + Import-Module PowerShellBuild -Force + New-PsakeDocusaurusHelp @psbOptions +} +#endregion PSB Command Reference Generation Tasks + #region Sync Front Matter Data Task -Name 'FrontMatterCMSSync' { ( diff --git a/requirements.psd1 b/requirements.psd1 index f1c3d07..fba0571 100644 --- a/requirements.psd1 +++ b/requirements.psd1 @@ -14,6 +14,9 @@ 'Microsoft.PowerShell.PlatyPS' = @{ Version = 'latest' } + 'PowerShellBuild' = @{ + Version = 'latest' + } 'Yayaml' = @{ Version = '0.6.0' } diff --git a/sidebars.ts b/sidebars.ts index 348039c..b23ed87 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -1,5 +1,6 @@ import type { SidebarsConfig } from '@docusaurus/plugin-content-docs'; import commands from "./docs/commands/docusaurus.sidebar.js"; +import psbCommands from "./docs/psb-commands/docusaurus.sidebar.js"; /** * Creating a sidebar enables you to: @@ -87,6 +88,11 @@ const sidebars: SidebarsConfig = { 'powershellbuild/task-reference', 'powershellbuild/configuration', 'powershellbuild/real-world-example', + ...(psbCommands.length > 0 ? [{ + type: 'category' as const, + label: 'Command Reference', + items: psbCommands, + }] : []), ], // Reference - Command reference, troubleshooting, and lookup materials From aeaebdb392add1ac4eb270212c093226df8cc489 Mon Sep 17 00:00:00 2001 From: Gilbert Sanchez Date: Fri, 24 Apr 2026 12:44:46 -0700 Subject: [PATCH 04/11] Generalize doc generator; add since badges; remove stale Exec page - Rename New-PsakeDocusaurusHelp.ps1 -> New-DocusaurusModuleHelp.ps1 - Rename function to New-DocusaurusModuleHelp (works for any PS module) - Add CommandVersionMap parameter; injects :::note Since X.Y::: admonition - Add CommandVersionMap to $docusaurusOptions for the 8 psake v5-only commands - Update both GenerateCommandReference-Gen and GenerateCommandReferencePSB-Gen to use new script/function - Remove Exec.mdx (command was renamed to Execute in psake v5; no longer exported) - Remove 'commands/Exec' from docusaurus.sidebar.js Co-Authored-By: Claude Sonnet 4.6 --- docs/commands/Exec.mdx | 183 -------------------- docs/commands/docusaurus.sidebar.js | 1 - psakeFile.ps1 | 18 +- scripts/New-DocusaurusModuleHelp.ps1 | 244 +++++++++++++++++++++++++++ 4 files changed, 258 insertions(+), 188 deletions(-) delete mode 100644 docs/commands/Exec.mdx create mode 100644 scripts/New-DocusaurusModuleHelp.ps1 diff --git a/docs/commands/Exec.mdx b/docs/commands/Exec.mdx deleted file mode 100644 index d81ef24..0000000 --- a/docs/commands/Exec.mdx +++ /dev/null @@ -1,183 +0,0 @@ ---- -id: Exec -title: Exec -description: Help page for the PowerShell Psake "Exec" command -keywords: - - PowerShell - - Psake - - Help - - Documentation -hide_title: false -hide_table_of_contents: false -custom_edit_url: null ---- - -:::info This page was generated -Contributions are welcome in [Psake-repo](https://github.com/psake/psake). -::: - -## SYNOPSIS - -Helper function for executing command-line programs. - -## SYNTAX - -```powershell -Exec [-cmd] [[-errorMessage] ] [[-maxRetries] ] - [[-retryTriggerErrorPattern] ] [[-workingDirectory] ] [-ProgressAction ] - [] -``` - -## DESCRIPTION - -This is a helper function that runs a scriptblock and checks the PS variable $lastexitcode to see if an error occcured. -If an error is detected then an exception is thrown. -This function allows you to run command-line programs without having to explicitly check fthe $lastexitcode variable. - -## EXAMPLES - -### EXAMPLE 1 - -```powershell -exec { svn info $repository_trunk } "Error executing SVN. Please verify SVN command-line client is installed" -``` - -This example calls the svn command-line client. - -## PARAMETERS - -### -cmd - -The scriptblock to execute. -This scriptblock will typically contain the command-line invocation. - -```yaml -Type: ScriptBlock -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -errorMessage - -The error message to display if the external command returned a non-zero exit code. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: False -Position: 2 -Default value: ($msgs.error_bad_command -f $cmd) -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -maxRetries - -The maximum number of times to retry the command before failing. - -```yaml -Type: Int32 -Parameter Sets: (All) -Aliases: - -Required: False -Position: 3 -Default value: 0 -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -retryTriggerErrorPattern - -If the external command raises an exception, match the exception against this regex to determine if the command can be retried. -If a match is found, the command will be retried provided [maxRetries] has not been reached. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: False -Position: 4 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -workingDirectory - -The working directory to set before running the external command. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: False -Position: 5 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -ProgressAction - -\{\{ Fill ProgressAction Description \}\} - -```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: proga - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### CommonParameters - -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -## OUTPUTS - -## NOTES - -## RELATED LINKS - -[Assert](Assert.mdx) - -[FormatTaskName](FormatTaskName.mdx) - -[Framework](Framework.mdx) - -[Get-PSakeScriptTasks](Get-PSakeScriptTasks.mdx) - -[Include](Include.mdx) - -[Invoke-psake](Invoke-psake.mdx) - -[Properties](Properties.mdx) - -[Task](Task.mdx) - -[TaskSetup](TaskSetup.mdx) - -[TaskTearDown](TaskTearDown.mdx) - -[Properties](Properties.mdx) - -## VERSION - -*This page was generated using comment-based help in [Psake 4.9.0](https://github.com/psake/psake).* diff --git a/docs/commands/docusaurus.sidebar.js b/docs/commands/docusaurus.sidebar.js index 06c324a..7b3e5f6 100644 --- a/docs/commands/docusaurus.sidebar.js +++ b/docs/commands/docusaurus.sidebar.js @@ -9,7 +9,6 @@ module.exports = [ 'commands/BuildSetup', 'commands/BuildTearDown', 'commands/Clear-PsakeCache', - 'commands/Exec', 'commands/Execute', 'commands/FormatTaskName', 'commands/Framework', diff --git a/psakeFile.ps1 b/psakeFile.ps1 index 89f5aaf..d252ad7 100644 --- a/psakeFile.ps1 +++ b/psakeFile.ps1 @@ -35,6 +35,16 @@ Contributions are welcome in [Psake-repo](https://github.com/psake/psake). *This page was generated using comment-based help in [Psake $($psakeVersion)](https://github.com/psake/psake).* "@ HelpVersion = "$($script:psakeVersion)" + CommandVersionMap = @{ + 'BuildSetup' = '5.0' + 'BuildTearDown' = '5.0' + 'Clear-PsakeCache' = '5.0' + 'Execute' = '5.0' + 'Get-PsakeBuildPlan' = '5.0' + 'Test-BuildEnvironment' = '5.0' + 'Test-PsakeTask' = '5.0' + 'Version' = '5.0' + } } $script:docsOutputFolder = Join-Path -Path $docusaurusOptions.DocsFolder -ChildPath $docusaurusOptions.Sidebar | Join-Path -ChildPath "*.*" @@ -144,9 +154,9 @@ Task -Name 'GenerateCommandReference-Clean' -Action { Task -Name "GenerateCommandReference-Gen" -Depends 'GenerateCommandReference-Clean' { Write-Host "Generating new MDX files using Microsoft.PowerShell.PlatyPS" -ForegroundColor Magenta - . "$PSScriptRoot\scripts\New-PsakeDocusaurusHelp.ps1" + . "$PSScriptRoot\scripts\New-DocusaurusModuleHelp.ps1" Import-Module Microsoft.PowerShell.PlatyPS -Force - New-PsakeDocusaurusHelp @docusaurusOptions + New-DocusaurusModuleHelp @docusaurusOptions } #endregion Command Reference Generation Tasks @@ -167,10 +177,10 @@ Task -Name 'GenerateCommandReferencePSB-Clean' -Action { Task -Name "GenerateCommandReferencePSB-Gen" -Depends 'GenerateCommandReferencePSB-Clean' { Write-Host "Generating new PSB MDX files using Microsoft.PowerShell.PlatyPS" -ForegroundColor Magenta New-Item -ItemType Directory -Path (Join-Path $psbOptions.DocsFolder $psbOptions.SideBar) -Force | Out-Null - . "$PSScriptRoot\scripts\New-PsakeDocusaurusHelp.ps1" + . "$PSScriptRoot\scripts\New-DocusaurusModuleHelp.ps1" Import-Module Microsoft.PowerShell.PlatyPS -Force Import-Module PowerShellBuild -Force - New-PsakeDocusaurusHelp @psbOptions + New-DocusaurusModuleHelp @psbOptions } #endregion PSB Command Reference Generation Tasks diff --git a/scripts/New-DocusaurusModuleHelp.ps1 b/scripts/New-DocusaurusModuleHelp.ps1 new file mode 100644 index 0000000..50477a9 --- /dev/null +++ b/scripts/New-DocusaurusModuleHelp.ps1 @@ -0,0 +1,244 @@ +function New-DocusaurusModuleHelp { + [CmdletBinding()] + param( + [Parameter(Mandatory)] [string] $Module, + [Parameter(Mandatory)] [string] $DocsFolder, + [Parameter(Mandatory)] [string] $SideBar, + [string] $EditUrl = 'null', + [string[]] $Exclude = @(), + [string] $MetaDescription = 'Help page for the PowerShell %1 command', + [string[]] $MetaKeywords = @('PowerShell', 'Help', 'Documentation'), + [string] $PrependMarkdown = '', + [string] $AppendMarkdown = '', + [string] $HelpVersion = '', + [hashtable] $CommandVersionMap = @{} + ) + + Import-Module $Module -Force + + $tempDir = Join-Path ([System.IO.Path]::GetTempPath()) "platyps_$(Get-Random)" + New-Item -ItemType Directory -Path $tempDir | Out-Null + + try { + New-MarkdownCommandHelp -ModuleInfo (Get-Module $Module) -OutputFolder $tempDir -Force | Out-Null + + $moduleSubDir = Join-Path $tempDir $Module + $mdFiles = Get-ChildItem -Path $moduleSubDir -Filter '*.md' | + Where-Object { $_.BaseName -notin $Exclude } | + Sort-Object BaseName + + $outputFolder = Join-Path $DocsFolder $SideBar + $allCommandNames = $mdFiles | Select-Object -ExpandProperty BaseName + $sidebarItems = [System.Collections.Generic.List[string]]::new() + + foreach ($mdFile in $mdFiles) { + $commandName = $mdFile.BaseName + + $sinceBadge = '' + if ($CommandVersionMap.ContainsKey($commandName)) { + $sinceVersion = $CommandVersionMap[$commandName] + $sinceBadge = @" +:::note Since $Module $sinceVersion +This command was introduced in $Module $sinceVersion and is not available in earlier versions. +::: +"@ + } + + $mdxContent = ConvertTo-DocusaurusMdx ` + -SourceFile $mdFile ` + -CommandName $commandName ` + -MetaDescription $MetaDescription ` + -MetaKeywords $MetaKeywords ` + -EditUrl $EditUrl ` + -PrependMarkdown $PrependMarkdown ` + -AppendMarkdown $AppendMarkdown ` + -AllCommandNames $allCommandNames ` + -SinceBadge $sinceBadge + + $outputPath = Join-Path $outputFolder "$commandName.mdx" + Set-Content -Path $outputPath -Value $mdxContent -Encoding UTF8 -NoNewline + Write-Host " Generated: $commandName.mdx" + + $sidebarItems.Add("'$SideBar/$commandName'") + } + + $sidebarEntries = ($sidebarItems | ForEach-Object { " $_" }) -join ",`n" + $sidebarContent = @" +/** + * Import this file in your Docusaurus ``sidebars.js`` file. + * + * Auto-generated by New-DocusaurusModuleHelp using Microsoft.PowerShell.PlatyPS. + */ + +module.exports = [ +$sidebarEntries +]; +"@ + $sidebarPath = Join-Path $outputFolder 'docusaurus.sidebar.js' + Set-Content -Path $sidebarPath -Value $sidebarContent -Encoding UTF8 -NoNewline + Write-Host " Generated: docusaurus.sidebar.js ($($sidebarItems.Count) commands)" + } + finally { + Remove-Item -Path $tempDir -Recurse -Force -ErrorAction SilentlyContinue + } +} + +function ConvertTo-DocusaurusMdx { + param( + [System.IO.FileInfo] $SourceFile, + [string] $CommandName, + [string] $MetaDescription, + [string[]] $MetaKeywords, + [string] $EditUrl, + [string] $PrependMarkdown, + [string] $AppendMarkdown, + [string[]] $AllCommandNames, + [string] $SinceBadge = '' + ) + + $raw = Get-Content -Path $SourceFile.FullName -Raw + + # Strip PlatyPS v2 frontmatter block + $body = $raw -replace '(?s)^---.*?---\s*', '' + + # Strip the H1 title line PlatyPS emits + $body = $body -replace '(?m)^# .+\r?\n', '' + + # Convert markdown parameter tables to yaml fenced blocks + $body = Convert-ParameterTablesToYamlFences -Body $body + + # Fix RELATED LINKS: [Name]() -> [Name](Name.mdx) for known commands, strip unknown + foreach ($cmd in $AllCommandNames) { + $escaped = [regex]::Escape($cmd) + $body = $body -replace "\[$escaped\]\(\)", "[$cmd]($cmd.mdx)" + } + $body = $body -replace '\[([^\]]+)\]\(\)', '$1' + + # Escape curly braces outside code fences (required for MDX/JSX compatibility) + $body = Escape-CurlyBracesOutsideCodeFences -Body $body + + # Build Docusaurus frontmatter + $description = $MetaDescription -replace '%1', $CommandName + $keywordsYaml = ($MetaKeywords | ForEach-Object { " - $_" }) -join "`n" + $customEditUrl = if ($EditUrl -eq 'null') { 'null' } else { "$EditUrl/$CommandName.ps1" } + + $frontmatter = @" +--- +id: $CommandName +title: $CommandName +description: $description +keywords: +$keywordsYaml +hide_title: false +hide_table_of_contents: false +custom_edit_url: $customEditUrl +--- +"@ + + $parts = [System.Collections.Generic.List[string]]::new() + $parts.Add($frontmatter) + if ($PrependMarkdown) { $parts.Add($PrependMarkdown.Trim()) } + if ($SinceBadge) { $parts.Add($SinceBadge.Trim()) } + $parts.Add($body.Trim()) + if ($AppendMarkdown) { $parts.Add($AppendMarkdown.Trim()) } + + return ($parts -join "`n`n") + "`n" +} + +function Convert-ParameterTablesToYamlFences { + param([string] $Body) + + # Match each ### -ParameterName block through to the next ### - or end of PARAMETERS section + $result = [System.Text.RegularExpressions.Regex]::Replace( + $Body, + '(?ms)(### -\w[^\r\n]*\r?\n)(.*?)(?=### -|\z)', + { + param($match) + $header = $match.Groups[1].Value + $content = $match.Groups[2].Value + + # Extract description text (everything before the first table row) + $descText = ($content -split '(?m)^\|')[0].TrimEnd() + + # Helper: extract a value from a markdown table row by property name + function Get-TableValue([string]$text, [string]$prop) { + if ($text -match "(?m)^\|\s*$([regex]::Escape($prop))\s*\|\s*([^|]+)\|") { + return $matches[1].Trim() + } + return $null + } + + $type = Get-TableValue $content 'Type:' + $mandatory = Get-TableValue $content 'Mandatory:' + $position = Get-TableValue $content 'Position:' + $default = Get-TableValue $content 'Default value:' + $pipeline = Get-TableValue $content 'Value from pipeline:' + $wildcard = Get-TableValue $content 'Supports wildcards:' + $aliases = Get-TableValue $content 'Aliases:' + + # Strip System. namespace prefix from types + if ($type) { $type = $type -replace '^System\.', '' } else { $type = 'None' } + + $required = if ($mandatory -eq 'True') { 'True' } else { 'False' } + + # v2 position is 0-based; v1 (target) is 1-based + if ($position -and $position -match '^\d+$') { + $position = [int]$position + 1 + } elseif (-not $position) { + $position = 'Named' + } + + if (-not $default) { $default = 'None' } + if (-not $pipeline) { $pipeline = 'False' } + if (-not $wildcard) { $wildcard = 'False' } + if (-not $aliases) { $aliases = '' } + + # Detect parameter sets - look for "Parameter sets" section in the content + $paramSets = '(All)' + if ($content -match '(?ms)Parameter sets\s*\r?\n\|[^\r\n]+\r?\n\|[^\r\n]+\r?\n\|\s*([^|]+)\|') { + $paramSets = $matches[1].Trim() + } + + $yamlFence = @" + +``````yaml +Type: $type +Parameter Sets: $paramSets +Aliases: $aliases + +Required: $required +Position: $position +Default value: $default +Accept pipeline input: $pipeline +Accept wildcard characters: $wildcard +`````` + +"@ + return $header + $descText + $yamlFence + } + ) + + return $result +} + +function Escape-CurlyBracesOutsideCodeFences { + param([string] $Body) + + # Split on fenced code blocks (``` delimiters), alternating outside/inside + $segments = [System.Text.RegularExpressions.Regex]::Split( + $Body, + '((?ms)^```[^\r\n]*\r?\n.*?^```\r?\n?)' + ) + + $result = for ($i = 0; $i -lt $segments.Count; $i++) { + if ($i % 2 -eq 0) { + # Outside a code fence — escape curly braces + $segments[$i] -replace '\{', '\{' -replace '\}', '\}' + } else { + # Inside a code fence — pass through unchanged + $segments[$i] + } + } + + return $result -join '' +} From e598ffa16becd88ef199514fa12df834b8025d91 Mon Sep 17 00:00:00 2001 From: Gilbert Sanchez Date: Tue, 28 Apr 2026 11:17:27 -0700 Subject: [PATCH 05/11] psake v5 best practices: caching, NoCache/OutputFormat flags, doc regen fix - psakeFile: add Inputs/Outputs caching to Init and FrontMatterCMSSync tasks - psakeFile: add PreCondition to GenerateCommandReferencePSB; convert all tasks to hashtable syntax; fix #requires statement - build.ps1: add -NoCache and -OutputFormat params; use splatting for Invoke-Psake - requirements.psd1: fix 'latest3' typo for psake version - New-DocusaurusModuleHelp: guard Import-Module with Get-Module check to prevent force-reimporting psake mid-run (was blowing away Restore-Environment scope) - Delete stale scripts/New-PsakeDocusaurusHelp.ps1 (superseded by New-DocusaurusModuleHelp) - .gitignore: add .psake/ (v5 task cache directory) - Regenerate all 19 command reference MDX files Co-Authored-By: Claude Sonnet 4.6 --- .gitignore | 3 + build.ps1 | 40 +- docs/commands/Assert.mdx | 121 ++--- docs/commands/BuildSetup.mdx | 91 ++-- docs/commands/BuildTearDown.mdx | 109 ++-- docs/commands/Clear-PsakeCache.mdx | 103 ++-- docs/commands/Execute.mdx | 246 ++++++--- docs/commands/FormatTaskName.mdx | 105 ++-- docs/commands/Framework.mdx | 104 ++-- docs/commands/Get-PSakeScriptTasks.mdx | 77 +-- docs/commands/Get-PsakeBuildPlan.mdx | 103 ++-- docs/commands/Include.mdx | 144 ++++-- docs/commands/Invoke-Task.mdx | 96 ++-- docs/commands/Invoke-psake.mdx | 577 ++++++++++++++++++--- docs/commands/Properties.mdx | 170 ++++-- docs/commands/Task.mdx | 655 ++++++++++++++++++++++-- docs/commands/TaskSetup.mdx | 119 ++--- docs/commands/TaskTearDown.mdx | 126 ++--- docs/commands/Test-BuildEnvironment.mdx | 126 +++-- docs/commands/Test-PsakeTask.mdx | 132 +++-- docs/commands/Version.mdx | 75 +-- docs/commands/docusaurus.sidebar.js | 8 +- psakeFile.ps1 | 196 ++++--- requirements.psd1 | 2 +- scripts/New-DocusaurusModuleHelp.ps1 | 4 +- scripts/New-PsakeDocusaurusHelp.ps1 | 229 --------- 26 files changed, 2406 insertions(+), 1355 deletions(-) delete mode 100644 scripts/New-PsakeDocusaurusHelp.ps1 diff --git a/.gitignore b/.gitignore index 6919d98..265a103 100644 --- a/.gitignore +++ b/.gitignore @@ -19,3 +19,6 @@ npm-debug.log* yarn-debug.log* yarn-error.log* bun-error.log + +# psake v5 task cache +.psake/ diff --git a/build.ps1 b/build.ps1 index e6606af..5797458 100644 --- a/build.ps1 +++ b/build.ps1 @@ -2,7 +2,7 @@ param( # Build task(s) to execute [parameter(ParameterSetName = 'task', position = 0)] - [ArgumentCompleter( { + [ArgumentCompleter({ param($Command, $Parameter, $WordToComplete, $CommandAst, $FakeBoundParams) try { Get-PSakeScriptTasks -BuildFile './psakeFile.ps1' -ErrorAction 'Stop' | @@ -12,32 +12,40 @@ param( @() } })] - [string[]]$Task = 'default', + [string[]] $Task = 'default', # Bootstrap dependencies - [switch]$Bootstrap, + [switch] $Bootstrap, # List available build tasks [parameter(ParameterSetName = 'Help')] - [switch]$Help, + [switch] $Help, - # Suppress console output (returns structured PsakeBuildResult) - [switch]$Quiet, + # Suppress console output; returns structured PsakeBuildResult. + # LLM should prefer this option. + [switch] $Quiet, + + # Bypass task caching for this run + [switch] $NoCache, + + # Output format for CI integration + [ValidateSet('Default', 'JSON', 'GitHubActions')] + [string] $OutputFormat = 'Default', # Optional properties to pass to psake - [hashtable]$Properties, + [hashtable] $Properties, # Optional parameters to pass to psake - [hashtable]$Parameters + [hashtable] $Parameters ) $ErrorActionPreference = 'Stop' # Bootstrap dependencies -if ($Bootstrap.IsPresent) { +if ($Bootstrap) { PackageManagement\Get-PackageProvider -Name Nuget -ForceBootstrap | Out-Null Set-PSRepository -Name PSGallery -InstallationPolicy Trusted - if ((Test-Path -Path ./requirements.psd1)) { + if (Test-Path -Path './requirements.psd1') { if (-not (Get-Module -Name PSDepend -ListAvailable)) { Install-Module -Name PSDepend -Repository PSGallery -Scope CurrentUser -Force } @@ -54,6 +62,16 @@ if ($PSCmdlet.ParameterSetName -eq 'Help') { Get-PSakeScriptTasks -BuildFile $psakeFile | Format-Table -Property Name, Description, Alias, DependsOn } else { - $result = Invoke-Psake -BuildFile $psakeFile -TaskList $Task -NoLogo -Properties $Properties -Parameters $Parameters -Quiet:$Quiet + $invokeSplat = @{ + BuildFile = $psakeFile + TaskList = $Task + NoLogo = $true + Properties = $Properties + Parameters = $Parameters + Quiet = $Quiet + NoCache = $NoCache + OutputFormat = $OutputFormat + } + $result = Invoke-Psake @invokeSplat exit ([int](-not $result.Success)) } diff --git a/docs/commands/Assert.mdx b/docs/commands/Assert.mdx index 2a2454d..1df5a7b 100644 --- a/docs/commands/Assert.mdx +++ b/docs/commands/Assert.mdx @@ -22,11 +22,17 @@ Helper function for "Design by Contract" assertion checking. ## SYNTAX -```powershell -Assert [-conditionToCheck] [-failureMessage] [-ProgressAction ] - [] +### __AllParameterSets + +``` +Assert [-ConditionToCheck] [-FailureMessage] [] ``` +## ALIASES + +This cmdlet has the following aliases, + \{\{Insert list of aliases\}\} + ## DESCRIPTION This is a helper function that makes the code less noisy by eliminating many of the "if" statements that are normally required to verify assumptions in the code. @@ -35,23 +41,19 @@ This is a helper function that makes the code less noisy by eliminating many of ### EXAMPLE 1 -```powershell Assert $false "This always throws an exception" -``` Example of an assertion that will always fail. ### EXAMPLE 2 -```powershell Assert ( ($i % 2) -eq 0 ) "$i is not an even number" -``` This exmaple may throw an exception if $i is not an even number Note: It might be necessary to wrap the condition with paranthesis to force PS to evaluate the condition -so that a boolean value is calculated and passed into the 'conditionToCheck' parameter. +so that a boolean value is calculated and passed into the 'ConditionToCheck' parameter. Example: Assert 1 -eq 2 "1 doesn't equal 2" @@ -65,57 +67,64 @@ Assert (1 -eq 2) "1 doesn't equal 2" ## PARAMETERS -### -conditionToCheck +### -ConditionToCheck The boolean condition to evaluate ```yaml -Type: Object -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False +Type: System.Object +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` - -### -failureMessage - -The error message used for the exception if the conditionToCheck parameter is false - ```yaml -Type: String +Type: None Parameter Sets: (All) -Aliases: +Aliases: -Required: True -Position: 2 +Required: False +Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False ``` +### -FailureMessage -### -ProgressAction - -\{\{ Fill ProgressAction Description \}\} +The error message used for the exception if the ConditionToCheck parameter is false ```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: proga - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 1 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -125,26 +134,18 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -[Exec](Exec.mdx) - -[FormatTaskName](FormatTaskName.mdx) - -[Framework](Framework.mdx) - -[Get-PSakeScriptTasks](Get-PSakeScriptTasks.mdx) - -[Include](Include.mdx) - -[Invoke-psake](Invoke-psake.mdx) - -[Properties](Properties.mdx) - -[Task](Task.mdx) - -[TaskSetup](TaskSetup.mdx) +\{\{ Fill in the related links here \}\} +```yaml +Type: None +Parameter Sets: (All) +Aliases: -[TaskTearDown](TaskTearDown.mdx) +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` ## VERSION - -*This page was generated using comment-based help in [Psake 4.9.0](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/BuildSetup.mdx b/docs/commands/BuildSetup.mdx index e764599..411c152 100644 --- a/docs/commands/BuildSetup.mdx +++ b/docs/commands/BuildSetup.mdx @@ -16,15 +16,26 @@ custom_edit_url: null Contributions are welcome in [Psake-repo](https://github.com/psake/psake). ::: +:::note Since Psake 5.0 +This command was introduced in Psake 5.0 and is not available in earlier versions. +::: + ## SYNOPSIS Adds a scriptblock that will be executed once at the beginning of the build ## SYNTAX -```powershell -BuildSetup [-Setup] [-ProgressAction ] [] +### __AllParameterSets + ``` +BuildSetup [-Setup] [] +``` + +## ALIASES + +This cmdlet has the following aliases, + \{\{Insert list of aliases\}\} ## DESCRIPTION @@ -35,18 +46,16 @@ beginning of the build. ### EXAMPLE 1 -```powershell Task default -Depends Test -Task Test -Depends Compile, Clean { -} -Task Compile -Depends Clean { -} -Task Clean { -} -BuildSetup { +Task Test -Depends Compile, Clean \{ +\} +Task Compile -Depends Clean \{ +\} +Task Clean \{ +\} +BuildSetup \{ "Running 'BuildSetup'" -} -``` +\} The script above produces the following output: Running 'BuildSetup' @@ -62,25 +71,42 @@ Build Succeeded A scriptblock to execute ```yaml -Type: ScriptBlock -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False +Type: System.Management.Automation.ScriptBlock +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` -### -ProgressAction +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS -\{\{ Fill ProgressAction Description \}\} +## OUTPUTS +## NOTES + +## RELATED LINKS + +\{\{ Fill in the related links here \}\} ```yaml -Type: ActionPreference +Type: None Parameter Sets: (All) -Aliases: proga +Aliases: Required: False Position: Named @@ -89,18 +115,5 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### CommonParameters - -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -## OUTPUTS - -## NOTES - -## RELATED LINKS - ## VERSION - -*This page was generated using comment-based help in [Psake 5.0.2](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/BuildTearDown.mdx b/docs/commands/BuildTearDown.mdx index 2167bbf..5cdcdcc 100644 --- a/docs/commands/BuildTearDown.mdx +++ b/docs/commands/BuildTearDown.mdx @@ -16,15 +16,26 @@ custom_edit_url: null Contributions are welcome in [Psake-repo](https://github.com/psake/psake). ::: +:::note Since Psake 5.0 +This command was introduced in Psake 5.0 and is not available in earlier versions. +::: + ## SYNOPSIS Adds a scriptblock that will be executed once at the end of the build ## SYNTAX -```powershell -BuildTearDown [-Setup] [-ProgressAction ] [] +### __AllParameterSets + ``` +BuildTearDown [-Setup] [] +``` + +## ALIASES + +This cmdlet has the following aliases, + \{\{Insert list of aliases\}\} ## DESCRIPTION @@ -35,18 +46,16 @@ end of the build, regardless of success or failure ### EXAMPLE 1 -```powershell Task default -Depends Test -Task Test -Depends Compile, Clean { -} -Task Compile -Depends Clean { -} -Task Clean { -} -BuildTearDown { +Task Test -Depends Compile, Clean \{ +\} +Task Compile -Depends Clean \{ +\} +Task Clean \{ +\} +BuildTearDown \{ "Running 'BuildTearDown'" -} -``` +\} The script above produces the following output: Executing task, Clean... @@ -57,19 +66,17 @@ Build Succeeded ### EXAMPLE 2 -```powershell Task default -Depends Test -Task Test -Depends Compile, Clean { +Task Test -Depends Compile, Clean \{ throw "forced error" -} -Task Compile -Depends Clean { -} -Task Clean { -} -BuildTearDown { +\} +Task Compile -Depends Clean \{ +\} +Task Clean \{ +\} +BuildTearDown \{ "Running 'BuildTearDown'" -} -``` +\} The script above produces the following output: Executing task, Clean... @@ -86,25 +93,42 @@ At line:x char:x ... A scriptblock to execute ```yaml -Type: ScriptBlock -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False +Type: System.Management.Automation.ScriptBlock +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` -### -ProgressAction +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS -\{\{ Fill ProgressAction Description \}\} +## NOTES + +## RELATED LINKS +\{\{ Fill in the related links here \}\} ```yaml -Type: ActionPreference +Type: None Parameter Sets: (All) -Aliases: proga +Aliases: Required: False Position: Named @@ -113,18 +137,5 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### CommonParameters - -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -## OUTPUTS - -## NOTES - -## RELATED LINKS - ## VERSION - -*This page was generated using comment-based help in [Psake 5.0.2](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Clear-PsakeCache.mdx b/docs/commands/Clear-PsakeCache.mdx index 7237c0c..1ec5ddc 100644 --- a/docs/commands/Clear-PsakeCache.mdx +++ b/docs/commands/Clear-PsakeCache.mdx @@ -16,16 +16,26 @@ custom_edit_url: null Contributions are welcome in [Psake-repo](https://github.com/psake/psake). ::: +:::note Since Psake 5.0 +This command was introduced in Psake 5.0 and is not available in earlier versions. +::: + ## SYNOPSIS Clears the psake build cache. ## SYNTAX -```powershell -Clear-PsakeCache [[-Path] ] [[-TaskName] ] [-ProgressAction ] - [] +### __AllParameterSets + ``` +Clear-PsakeCache [[-Path] ] [[-TaskName] ] [] +``` + +## ALIASES + +This cmdlet has the following aliases, + \{\{Insert list of aliases\}\} ## DESCRIPTION @@ -36,17 +46,13 @@ This forces all tasks to re-execute on the next build. ### EXAMPLE 1 -```powershell Clear-PsakeCache -``` Clears all cached task state in the current directory. ### EXAMPLE 2 -```powershell Clear-PsakeCache -TaskName 'Build' -``` Clears cached state for the 'Build' task only. @@ -59,52 +65,59 @@ Defaults to the current directory. ```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: False -Position: 1 -Default value: . -Accept pipeline input: False -Accept wildcard characters: False +Type: System.String +DefaultValue: . +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` - -### -TaskName - -Optional: clear cache for a specific task only. - ```yaml -Type: String +Type: None Parameter Sets: (All) -Aliases: +Aliases: Required: False -Position: 2 +Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False ``` +### -TaskName -### -ProgressAction - -\{\{ Fill ProgressAction Description \}\} +Optional: clear cache for a specific task only. ```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: proga - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 1 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -114,8 +127,18 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -[Invoke-psake](Invoke-psake.mdx) +- [Invoke-Psake](Invoke-Psake.mdx) +```yaml +Type: None +Parameter Sets: (All) +Aliases: -## VERSION +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` -*This page was generated using comment-based help in [Psake 5.0.2](https://github.com/psake/psake).* +## VERSION +*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Execute.mdx b/docs/commands/Execute.mdx index 83d07db..3f9fd20 100644 --- a/docs/commands/Execute.mdx +++ b/docs/commands/Execute.mdx @@ -16,17 +16,28 @@ custom_edit_url: null Contributions are welcome in [Psake-repo](https://github.com/psake/psake). ::: +:::note Since Psake 5.0 +This command was introduced in Psake 5.0 and is not available in earlier versions. +::: + ## SYNOPSIS Helper function for executing command-line programs. ## SYNTAX -```powershell -Execute [-Cmd] [[-ErrorMessage] ] [[-MaxRetries] ] - [[-RetryTriggerErrorPattern] ] [[-WorkingDirectory] ] [-NewProcess] - [[-TimeoutSeconds] ] [-ProgressAction ] [] +### __AllParameterSets + ``` +Execute [-Cmd] [[-ErrorMessage] ] [[-MaxRetries] ] + [[-RetryTriggerErrorPattern] ] [[-WorkingDirectory] ] [[-TimeoutSeconds] ] + [-NewProcess] [] +``` + +## ALIASES + +This cmdlet has the following aliases, + \{\{Insert list of aliases\}\} ## DESCRIPTION @@ -41,9 +52,7 @@ explicitly check the $lastexitcode variable. ### EXAMPLE 1 -```powershell -Execute { svn info $repository_trunk } "Error executing SVN. Please verify SVN command-line client is installed" -``` +Execute \{ svn info $repository_trunk \} "Error executing SVN. Please verify SVN command-line client is installed" This example calls the svn command-line client. @@ -56,103 +65,162 @@ This scriptblock will typically contain the command-line invocation. ```yaml -Type: ScriptBlock +Type: System.Management.Automation.ScriptBlock +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` +```yaml +Type: None Parameter Sets: (All) -Aliases: +Aliases: -Required: True -Position: 1 +Required: False +Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False ``` - ### -ErrorMessage The error message to display if the external command returned a non-zero exit code. ```yaml -Type: String +Type: System.String +DefaultValue: ($msgs.error_bad_command -f $Cmd.ToString().Trim()) +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 1 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` +```yaml +Type: None Parameter Sets: (All) -Aliases: +Aliases: Required: False -Position: 2 -Default value: ($msgs.error_bad_command -f $Cmd.ToString().Trim()) +Position: Named +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` - ### -MaxRetries The maximum number of times to retry the command before failing. ```yaml -Type: Int32 -Parameter Sets: (All) -Aliases: - -Required: False -Position: 3 -Default value: 0 -Accept pipeline input: False -Accept wildcard characters: False +Type: System.Int32 +DefaultValue: 0 +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 2 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` - -### -RetryTriggerErrorPattern - -If the external command raises an exception, match the exception against -this regex to determine if the command can be retried. -If a match is found, -the command will be retried provided [MaxRetries] has not been reached. - ```yaml -Type: String +Type: None Parameter Sets: (All) -Aliases: +Aliases: Required: False -Position: 4 +Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False ``` +### -NewProcess -### -WorkingDirectory - -The working directory to set before running the external command. +If set, the command will be executed in a new process. +This can be used to +isolate the command's environment from the current process. ```yaml -Type: String +Type: System.Management.Automation.SwitchParameter +DefaultValue: False +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` +```yaml +Type: None Parameter Sets: (All) -Aliases: wd +Aliases: Required: False -Position: 5 +Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False ``` +### -RetryTriggerErrorPattern -### -NewProcess - -If set, the command will be executed in a new process. -This can be used to -isolate the command's environment from the current process. +If the external command raises an exception, match the exception against +this regex to determine if the command can be retried. +If a match is found, +the command will be retried provided [MaxRetries] has not been reached. ```yaml -Type: SwitchParameter +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 3 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` +```yaml +Type: None Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named -Default value: False +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` - ### -TimeoutSeconds If set, the command will be terminated if it runs longer than this number of @@ -160,25 +228,25 @@ seconds. Defaults to 300 seconds (5 minutes). ```yaml -Type: Int32 -Parameter Sets: (All) -Aliases: - -Required: False -Position: 6 -Default value: 300 -Accept pipeline input: False -Accept wildcard characters: False +Type: System.Int32 +DefaultValue: 300 +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 5 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` - -### -ProgressAction - -\{\{ Fill ProgressAction Description \}\} - ```yaml -Type: ActionPreference +Type: None Parameter Sets: (All) -Aliases: proga +Aliases: Required: False Position: Named @@ -186,10 +254,34 @@ Default value: None Accept pipeline input: False Accept wildcard characters: False ``` +### -WorkingDirectory + +The working directory to set before running the external command. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: +- wd +ParameterSets: +- Name: (All) + Position: 4 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -199,6 +291,18 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -## VERSION +\{\{ Fill in the related links here \}\} +```yaml +Type: None +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` -*This page was generated using comment-based help in [Psake 5.0.2](https://github.com/psake/psake).* +## VERSION +*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/FormatTaskName.mdx b/docs/commands/FormatTaskName.mdx index b892022..bbc0f8f 100644 --- a/docs/commands/FormatTaskName.mdx +++ b/docs/commands/FormatTaskName.mdx @@ -22,10 +22,17 @@ This function allows you to change how psake renders the task name during a buil ## SYNTAX -```powershell -FormatTaskName [-format] [-ProgressAction ] [] +### __AllParameterSets + +``` +FormatTaskName [-Format] [] ``` +## ALIASES + +This cmdlet has the following aliases, + \{\{Insert list of aliases\}\} + ## DESCRIPTION This function takes either a string which represents a format string (formats using the -f format operator see "help about_operators") or it can accept a script block that has a single parameter that is the name of the task that will be executed. @@ -34,24 +41,22 @@ This function takes either a string which represents a format string (formats us ### EXAMPLE 1 -```powershell A sample build script that uses a format string is shown below: -``` Task default -depends TaskA, TaskB, TaskC FormatTaskName "-------- \{0\} --------" Task TaskA \{ - "TaskA is executing" +"TaskA is executing" \} Task TaskB \{ - "TaskB is executing" +"TaskB is executing" \} Task TaskC \{ - "TaskC is executing" +"TaskC is executing" ----------- The script above produces the following output: @@ -67,9 +72,7 @@ Build Succeeded! ### EXAMPLE 2 -```powershell A sample build script that uses a ScriptBlock is shown below: -``` Task default -depends TaskA, TaskB, TaskC @@ -79,15 +82,15 @@ FormatTaskName \{ \} Task TaskA \{ - "TaskA is executing" +"TaskA is executing" \} Task TaskB \{ - "TaskB is executing" +"TaskB is executing" \} Task TaskC \{ - "TaskC is executing" +"TaskC is executing" \} ----------- @@ -97,41 +100,33 @@ Note: the $taskName parameter is arbitrary, it could be named anything. ## PARAMETERS -### -format +### -Format A format string or a scriptblock to execute ```yaml -Type: Object -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -ProgressAction - -\{\{ Fill ProgressAction Description \}\} - -```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: proga - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False +Type: System.Object +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -141,26 +136,18 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -[Assert](Assert.mdx) - -[Exec](Exec.mdx) - -[Framework](Framework.mdx) - -[Get-PSakeScriptTasks](Get-PSakeScriptTasks.mdx) - -[Include](Include.mdx) - -[Invoke-psake](Invoke-psake.mdx) - -[Properties](Properties.mdx) - -[Task](Task.mdx) - -[TaskSetup](TaskSetup.mdx) +\{\{ Fill in the related links here \}\} +```yaml +Type: None +Parameter Sets: (All) +Aliases: -[TaskTearDown](TaskTearDown.mdx) +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` ## VERSION - -*This page was generated using comment-based help in [Psake 4.9.0](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Framework.mdx b/docs/commands/Framework.mdx index 91e7b9d..bd53aaa 100644 --- a/docs/commands/Framework.mdx +++ b/docs/commands/Framework.mdx @@ -22,70 +22,68 @@ Sets the version of the .NET framework you want to use during build. ## SYNTAX -```powershell -Framework [-framework] [-ProgressAction ] [] +### __AllParameterSets + +``` +Framework [-Framework] [] ``` +## ALIASES + +This cmdlet has the following aliases, + \{\{Insert list of aliases\}\} + ## DESCRIPTION -This function will accept a string containing version of the .NET framework to use during build. -Possible values: '1.0', '1.1', '2.0', '2.0x86', '2.0x64', '3.0', '3.0x86', '3.0x64', '3.5', '3.5x86', '3.5x64', '4.0', '4.0x86', '4.0x64', '4.5', '4.5x86', '4.5x64', '4.5.1', '4.5.1x86', '4.5.1x64'. -Default is '3.5*', where x86 or x64 will be detected based on the bitness of the PowerShell process. +This function will accept a string containing version of the .NET framework +to use during build. +Possible values: '1.0', '1.1', '2.0', '2.0x86', '2.0x64', '3.0', '3.0x86', +'3.0x64', '3.5', '3.5x86', '3.5x64', '4.0', '4.0x86', '4.0x64', '4.5', +'4.5x86', '4.5x64', '4.5.1', '4.5.1x86', '4.5.1x64'. +Default is '3.5*', where x86 or x64 will be detected based on the bitness of +the PowerShell process. ## EXAMPLES ### EXAMPLE 1 -```powershell Framework "4.0" -``` - Task default -depends Compile - Task Compile -depends Clean \{ msbuild /version \} ------------ The script above will output detailed version of msbuid v4 ## PARAMETERS -### -framework +### -Framework Version of the .NET framework to use during build. ```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -ProgressAction - -\{\{ Fill ProgressAction Description \}\} - -```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: proga - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -95,26 +93,18 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -[Assert](Assert.mdx) - -[Exec](Exec.mdx) - -[FormatTaskName](FormatTaskName.mdx) - -[Get-PSakeScriptTasks](Get-PSakeScriptTasks.mdx) - -[Include](Include.mdx) - -[Invoke-psake](Invoke-psake.mdx) - -[Properties](Properties.mdx) - -[Task](Task.mdx) - -[TaskSetup](TaskSetup.mdx) +\{\{ Fill in the related links here \}\} +```yaml +Type: None +Parameter Sets: (All) +Aliases: -[TaskTearDown](TaskTearDown.mdx) +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` ## VERSION - -*This page was generated using comment-based help in [Psake 4.9.0](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Get-PSakeScriptTasks.mdx b/docs/commands/Get-PSakeScriptTasks.mdx index 86cda12..3aab1d8 100644 --- a/docs/commands/Get-PSakeScriptTasks.mdx +++ b/docs/commands/Get-PSakeScriptTasks.mdx @@ -22,10 +22,17 @@ Returns meta data about all the tasks defined in the provided psake script. ## SYNTAX -```powershell -Get-PSakeScriptTasks [[-buildFile] ] [-ProgressAction ] [] +### __AllParameterSets + +``` +Get-PSakeScriptTasks [[-BuildFile] ] [] ``` +## ALIASES + +This cmdlet has the following aliases, + \{\{Insert list of aliases\}\} + ## DESCRIPTION Returns meta data about all the tasks defined in the provided psake script. @@ -34,9 +41,7 @@ Returns meta data about all the tasks defined in the provided psake script. ### EXAMPLE 1 -```powershell -Get-PSakeScriptTasks -buildFile '.\build.ps1' -``` +Get-PSakeScriptTasks -BuildFile '.\build.ps1' DependsOn Alias Name Description --------- ----- ---- ----------- @@ -49,41 +54,33 @@ Gets the psake tasks contained in the 'build.ps1' file. ## PARAMETERS -### -buildFile +### -BuildFile The path to the psake build script to read the tasks from. ```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: False -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -ProgressAction - -\{\{ Fill ProgressAction Description \}\} - -```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: proga - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -93,8 +90,18 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -[Invoke-psake](Invoke-psake.mdx) +\{\{ Fill in the related links here \}\} +```yaml +Type: None +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` ## VERSION - -*This page was generated using comment-based help in [Psake 4.9.0](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Get-PsakeBuildPlan.mdx b/docs/commands/Get-PsakeBuildPlan.mdx index bca641c..ff9e68e 100644 --- a/docs/commands/Get-PsakeBuildPlan.mdx +++ b/docs/commands/Get-PsakeBuildPlan.mdx @@ -16,16 +16,26 @@ custom_edit_url: null Contributions are welcome in [Psake-repo](https://github.com/psake/psake). ::: +:::note Since Psake 5.0 +This command was introduced in Psake 5.0 and is not available in earlier versions. +::: + ## SYNOPSIS Compiles a build file and returns the build plan without executing any tasks. ## SYNTAX -```powershell -Get-PsakeBuildPlan [[-BuildFile] ] [[-TaskList] ] [-ProgressAction ] - [] +### __AllParameterSets + ``` +Get-PsakeBuildPlan [[-BuildFile] ] [[-TaskList] ] [] +``` + +## ALIASES + +This cmdlet has the following aliases, + \{\{Insert list of aliases\}\} ## DESCRIPTION @@ -48,31 +58,25 @@ resolve properties, setup, and teardown blocks. ### EXAMPLE 1 -```powershell $plan = Get-PsakeBuildPlan -BuildFile './psakefile.ps1' $plan.Tasks | Should -HaveCount 4 $plan.ExecutionOrder | Should -Be @('Clean', 'Compile', 'Test', 'Default') -``` This example compiles the build file and asserts that there are 4 tasks and that the execution order is correct. ### EXAMPLE 2 -```powershell $plan = Get-PsakeBuildPlan $plan.TaskMap['build'].DependsOn | Should -Contain 'Clean' $plan.IsValid | Should -BeTrue -``` This example compiles the default build file and asserts that the 'build' task depends on the 'Clean' task and that the plan is valid. ### EXAMPLE 3 -```powershell Get-PsakeBuildPlan -BuildFile './psakefile.ps1' | Invoke-Psake -``` Compiles the build plan and pipes it into Invoke-Psake for execution. Note: the build file is re-loaded during the execution phase. @@ -85,42 +89,74 @@ The path to the psake build script. Defaults to 'psakefile.ps1'. ```yaml -Type: String +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` +```yaml +Type: None Parameter Sets: (All) -Aliases: +Aliases: Required: False -Position: 1 +Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False ``` - ### -TaskList A list of task names to include in the plan. Defaults to 'default'. ```yaml -Type: String[] -Parameter Sets: (All) -Aliases: - -Required: False -Position: 2 -Default value: @('default') -Accept pipeline input: False -Accept wildcard characters: False +Type: System.String[] +DefaultValue: "@('default')" +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 1 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` -### -ProgressAction +### CommonParameters -\{\{ Fill ProgressAction Description \}\} +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +## INPUTS + +## OUTPUTS + +## NOTES + +## RELATED LINKS + +\{\{ Fill in the related links here \}\} ```yaml -Type: ActionPreference +Type: None Parameter Sets: (All) -Aliases: proga +Aliases: Required: False Position: Named @@ -129,18 +165,5 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### CommonParameters - -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -## OUTPUTS - -## NOTES - -## RELATED LINKS - ## VERSION - -*This page was generated using comment-based help in [Psake 5.0.2](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Include.mdx b/docs/commands/Include.mdx index 65f816e..e839495 100644 --- a/docs/commands/Include.mdx +++ b/docs/commands/Include.mdx @@ -18,72 +18,87 @@ Contributions are welcome in [Psake-repo](https://github.com/psake/psake). ## SYNOPSIS -Include the functions or code of another powershell script file into the current build script's scope +Include the functions or code of another powershell script file into the +current build script's scope ## SYNTAX -```powershell -Include [-fileNamePathToInclude] [-ProgressAction ] [] +### Path (Default) + +``` +Include [-Path] [] ``` +### LiteralPath + +``` +Include [-LiteralPath] [] +``` + +## ALIASES + +This cmdlet has the following aliases, + \{\{Insert list of aliases\}\} + ## DESCRIPTION -A build script may declare an "includes" function which allows you to define a file containing powershell code to be included -and added to the scope of the currently running build script. -Code from such file will be executed after code from build script. +A build script may declare an "includes" function which allows you to define +a file containing powershell code to be included and added to the scope of +the currently running build script. +Code from such file will be executed +after code from build script. ## EXAMPLES ### EXAMPLE 1 -```powershell -A sample build script is shown below: -``` - Include ".\build_utils.ps1" - Task default -depends Test - Task Test -depends Compile, Clean \{ \} - Task Compile -depends Clean \{ \} - Task Clean \{ \} ------------ The script above includes all the functions and variables defined in the ".\build_utils.ps1" script into the current build script's scope Note: You can have more than 1 "Include" function defined in the build script. -## PARAMETERS - -### -fileNamePathToInclude +### EXAMPLE 2 -A string containing the path and name of the powershell file to include +@("File1.ps1","File2.ps1") | Include +Get-ChildItem | Include -```yaml -Type: String -Parameter Sets: (All) -Aliases: +Strings or FileInfo objects can be piped to the Include function -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` +## PARAMETERS -### -ProgressAction +### -LiteralPath -\{\{ Fill ProgressAction Description \}\} +A string containing the path and name of the powershell file to include (no +wildcards) ```yaml -Type: ActionPreference +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: LiteralPath + Position: 0 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: true + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` +```yaml +Type: None Parameter Sets: (All) -Aliases: proga +Aliases: Required: False Position: Named @@ -91,39 +106,60 @@ Default value: None Accept pipeline input: False Accept wildcard characters: False ``` +### -Path + +A string containing the path and name of the powershell file to include +(wildcards can be used) + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: true +Aliases: +- fileNamePathToInclude +ParameterSets: +- Name: Path + Position: 0 + IsRequired: true + ValueFromPipeline: true + ValueFromPipelineByPropertyName: true + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS +### System.String + +\{\{ Fill in the Description \}\} + ## OUTPUTS ## NOTES ## RELATED LINKS -[Assert](Assert.mdx) - -[Exec](Exec.mdx) - -[FormatTaskName](FormatTaskName.mdx) - -[Framework](Framework.mdx) - -[Get-PSakeScriptTasks](Get-PSakeScriptTasks.mdx) - -[Invoke-psake](Invoke-psake.mdx) - -[Properties](Properties.mdx) - -[Task](Task.mdx) - -[TaskSetup](TaskSetup.mdx) +\{\{ Fill in the related links here \}\} +```yaml +Type: None +Parameter Sets: (All) +Aliases: -[TaskTearDown](TaskTearDown.mdx) +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` ## VERSION - -*This page was generated using comment-based help in [Psake 4.9.0](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Invoke-Task.mdx b/docs/commands/Invoke-Task.mdx index 328c348..9b1508c 100644 --- a/docs/commands/Invoke-Task.mdx +++ b/docs/commands/Invoke-Task.mdx @@ -22,61 +22,59 @@ Executes another task in the current build script. ## SYNTAX -```powershell -Invoke-Task [-taskName] [-ProgressAction ] [] +### __AllParameterSets + +``` +Invoke-Task [-TaskName] [] ``` +## ALIASES + +This cmdlet has the following aliases, + \{\{Insert list of aliases\}\} + ## DESCRIPTION -This is a function that will allow you to invoke a Task from within another Task in the current build script. +This is a function that will allow you to invoke a Task from within another +Task in the current build script. ## EXAMPLES ### EXAMPLE 1 -```powershell Invoke-Task "Compile" -``` This example calls the "Compile" task. ## PARAMETERS -### -taskName +### -TaskName The name of the task to execute. ```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -ProgressAction - -\{\{ Fill ProgressAction Description \}\} - -```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: proga - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -86,28 +84,18 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -[Assert](Assert.mdx) - -[Exec](Exec.mdx) - -[FormatTaskName](FormatTaskName.mdx) - -[Framework](Framework.mdx) - -[Get-PSakeScriptTasks](Get-PSakeScriptTasks.mdx) - -[Include](Include.mdx) - -[Invoke-psake](Invoke-psake.mdx) - -[Properties](Properties.mdx) - -[Task](Task.mdx) - -[TaskSetup](TaskSetup.mdx) +\{\{ Fill in the related links here \}\} +```yaml +Type: None +Parameter Sets: (All) +Aliases: -[TaskTearDown](TaskTearDown.mdx) +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` ## VERSION - -*This page was generated using comment-based help in [Psake 4.9.0](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Invoke-psake.mdx b/docs/commands/Invoke-psake.mdx index 4b02b36..5762f6e 100644 --- a/docs/commands/Invoke-psake.mdx +++ b/docs/commands/Invoke-psake.mdx @@ -1,7 +1,7 @@ --- -id: Invoke-psake -title: Invoke-psake -description: Help page for the PowerShell Psake "Invoke-psake" command +id: Invoke-Psake +title: Invoke-Psake +description: Help page for the PowerShell Psake "Invoke-Psake" command keywords: - PowerShell - Psake @@ -22,172 +22,581 @@ Runs a psake build script. ## SYNTAX -```powershell -Invoke-psake [[-buildFile] ] [[-taskList] ] [[-framework] ] [-docs] - [[-parameters] ] [[-properties] ] [[-initialization] ] [-nologo] - [-detailedDocs] [-notr] [-ProgressAction ] [] +### __AllParameterSets + +``` +Invoke-Psake [[-BuildFile] ] [[-TaskList] ] [[-Framework] ] [-Docs] + [[-Parameters] ] [[-Properties] ] [[-Initialization] ] [-NoLogo] + [-DetailedDocs] [-NoTimeReport] [-OutputFormat ] [-NoCache] [-CompileOnly] [-Quiet] + [-BuildPlan ] [] ``` +## ALIASES + +This cmdlet has the following aliases, + \{\{Insert list of aliases\}\} + ## DESCRIPTION -This function runs a psake build script +This function runs a psake build script using a two-phase compile/run model. +The compile phase loads the build file and validates the dependency graph. +The run phase executes tasks in the resolved order. + +A pre-compiled [PsakeBuildPlan] from Get-PsakeBuildPlan can be piped in to +skip the compile phase. +When doing so, the build file is re-loaded for the +execution phase to resolve properties, setup, and teardown blocks. ## EXAMPLES ### EXAMPLE 1 -```powershell Invoke-psake -``` -Runs the 'default' task in the '.build.ps1' build script +Runs the 'default' task in the 'psakefile.ps1' build script ### EXAMPLE 2 -```powershell Invoke-psake '.\build.ps1' Tests,Package -``` -Runs the 'Tests' and 'Package' tasks in the '.build.ps1' build script +Runs the 'Tests' and 'Package' tasks in the 'build.ps1' build script ### EXAMPLE 3 -```powershell -Invoke-psake Tests -``` +Invoke-psake -CompileOnly -This example will run the 'Tests' tasks in the 'psakefile.ps1' build script. -The 'psakefile.ps1' is assumed to be in the current directory. +Returns the build plan without executing any tasks. ### EXAMPLE 4 -```powershell -Invoke-psake 'Tests, Package' -``` +Get-PsakeBuildPlan | Invoke-Psake -This example will run the 'Tests' and 'Package' tasks in the 'psakefile.ps1' build script. -The 'psakefile.ps1' is assumed to be in the current directory. +Compiles the build plan then executes it. +The build file is re-loaded +during the execution phase. ### EXAMPLE 5 -```powershell -Invoke-psake .\build.ps1 -docs +Invoke-psake -OutputFormat JSON + +Runs the build and outputs the result as JSON. + +## PARAMETERS + +### -BuildFile + +The path to the psake build script to execute + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` +```yaml +Type: None +Parameter Sets: (All) +Aliases: -Prints a report of all the tasks and their dependencies and descriptions and then exits +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` +### -BuildPlan -### EXAMPLE 6 +A pre-compiled [PsakeBuildPlan] to execute, typically from Get-PsakeBuildPlan +via the pipeline. +Compile-phase parameters (BuildFile, TaskList, Framework, +Docs, DetailedDocs, CompileOnly) are ignored when a plan is provided. +Note: the build file is re-loaded during the execution phase. -```powershell -Invoke-psake .\parameters.ps1 -parameters @{"p1"="v1";"p2"="v2"} +```yaml +Type: PsakeBuildPlan +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: true + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` +```yaml +Type: None +Parameter Sets: (All) +Aliases: -Runs the build script called 'parameters.ps1' and passes in parameters 'p1' and 'p2' with values 'v1' and 'v2' +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` +### -CompileOnly -Here's the .\parameters.ps1 build script: +Return the build plan without executing any tasks. +Delegates to +Get-PsakeBuildPlan. +Useful for tooling and testing. -properties \{ - $my_property = $p1 + $p2 -\} +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: False +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` +```yaml +Type: None +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` +### -DetailedDocs -task default -depends TestParams +Prints a more descriptive list of tasks and their descriptions. -task TestParams \{ - Assert ($my_property -ne $null) '$my_property should not be null' -\} +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: False +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 8 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` +```yaml +Type: None +Parameter Sets: (All) +Aliases: -Notice how you can refer to the parameters that were passed into the script from within the "properties" function. -The value of the $p1 variable should be the string "v1" and the value of the $p2 variable should be "v2". +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` +### -Docs -### EXAMPLE 7 +Prints a list of tasks and their descriptions -```powershell -Invoke-psake .\properties.ps1 -properties @{"x"="1";"y"="2"} +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: False +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 3 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` +```yaml +Type: None +Parameter Sets: (All) +Aliases: -Runs the build script called 'properties.ps1' and passes in parameters 'x' and 'y' with values '1' and '2' +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` +### -Framework -This feature allows you to override existing properties in your build script. +The version of the .NET framework you want to use during build. +You can +append x86 or x64 to force a specific framework. +If not specified, x86 or +x64 will be detected based on the bitness of the PowerShell process. +Possible values: '4.0', '4.0x86', '4.0x64', '4.5', '4.5x86', '4.5x64', +'4.5.1', '4.5.1x86', '4.5.1x64', '4.6', '4.6.1', '4.6.2', '4.7', '4.7.1', +'4.7.2', '4.8', '4.8.1' -Here's the .\properties.ps1 build script: +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 2 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` +```yaml +Type: None +Parameter Sets: (All) +Aliases: -properties \{ - $x = $null - $y = $null - $z = $null -\} +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` +### -Initialization -task default -depends TestProperties +A script block that will be executed before the tasks are executed. -task TestProperties \{ - Assert ($x -ne $null) "x should not be null" - Assert ($y -ne $null) "y should not be null" - Assert ($z -eq $null) "z should be null" -\} +```yaml +Type: System.Management.Automation.ScriptBlock +DefaultValue: '{}' +SupportsWildcards: false +Aliases: +- init +ParameterSets: +- Name: (All) + Position: 6 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` +```yaml +Type: None +Parameter Sets: (All) +Aliases: -## PARAMETERS +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` +### -NoCache -### -buildFile +Bypass task caching. +All tasks will execute regardless of cache state. -The path to the psake build script to execute +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: False +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` +```yaml +Type: None +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` +### -NoLogo + +Do not display the startup banner and copyright message. ```yaml -Type: String +Type: System.Management.Automation.SwitchParameter +DefaultValue: False +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 7 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` +```yaml +Type: None Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` +### -NoTimeReport + +Do not display the time report. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: False +SupportsWildcards: false Aliases: +- notr +ParameterSets: +- Name: (All) + Position: 9 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` +```yaml +Type: None +Parameter Sets: (All) +Aliases: Required: False -Position: 1 +Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False ``` +### -OutputFormat -### -taskList +The output format. +'Default' for console output, 'JSON' for JSON to stdout, +'GitHubActions' for GitHub Actions workflow annotations (::error::, ::warning::, ::debug::), +'Annotated' for colored console output plus annotation lines for errors/warnings (VS Code problem matcher). +If not specified, the PSAKE_OUTPUT_FORMAT environment variable is checked as a fallback. -A comma-separated list of task names to execute +```yaml +Type: System.String +DefaultValue: Default +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` +```yaml +Type: None +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` +### -Parameters + +A hashtable containing parameters to be passed into the current build +script. +These parameters will be processed before the 'Properties' function +of the script is processed. ```yaml -Type: String[] +Type: System.Collections.Hashtable +DefaultValue: '@{}' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 4 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` +```yaml +Type: None Parameter Sets: (All) -Aliases: +Aliases: Required: False -Position: 2 -Default value: @() +Position: Named +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` +### -Properties -### -framework +A hashtable containing properties to be passed into the current build +script. +These properties will override matching properties that are found in +the 'Properties' function of the script. -The version of the .NET framework you want to use during build. -You can append x86 or x64 to force a specific framework. -If not specified, x86 or x64 will be detected based on the bitness of the PowerShell process. -Possible values: '1.0', '1.1', '2.0', '2.0x86', '2.0x64', '3.0', '3.0x86', '3.0x64', '3.5', '3.5x86', '3.5x64', '4.0', '4.0x86', '4.0x64', '4.5', '4.5x86', '4.5x64', '4.5.1', '4.5.1x86', '4.5.1x64' +```yaml +Type: System.Collections.Hashtable +DefaultValue: '@{}' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 5 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` +```yaml +Type: None +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` +### -Quiet + +Suppress all console output. +The PsakeBuildResult is still returned. ```yaml -Type: String +Type: System.Management.Automation.SwitchParameter +DefaultValue: False +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` +```yaml +Type: None Parameter Sets: (All) -Aliases: +Aliases: Required: False -Position: 3 +Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False ``` +### -TaskList -### -docs +A comma-separated list of task names to execute -Prints a list of tasks and their descriptions +```yaml +Type: System.String[] +DefaultValue: "@('default')" +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 1 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### PsakeBuildPlan + +\{\{ Fill in the Description \}\} +## OUTPUTS + +## NOTES + +## RELATED LINKS + +\{\{ Fill in the related links here \}\} ```yaml -Type: SwitchParameter +Type: None Parameter Sets: (All) -Aliases: +Aliases: Required: False -Position: 4 -Default value: False -Acc +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +## VERSION +*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Properties.mdx b/docs/commands/Properties.mdx index 23e8d9a..6678fb1 100644 --- a/docs/commands/Properties.mdx +++ b/docs/commands/Properties.mdx @@ -18,70 +18,109 @@ Contributions are welcome in [Psake-repo](https://github.com/psake/psake). ## SYNOPSIS -Define a scriptblock that contains assignments to variables that will be available to all tasks in the build script +Define a scriptblock that contains assignments to variables that will be +available within all tasks in the build script ## SYNTAX -```powershell -Properties [-properties] [-ProgressAction ] [] +### ScriptBlock (Default) + +``` +Properties [-Properties] [] ``` +### Hashtable + +``` +Properties [-Hashtable] [] +``` + +## ALIASES + +This cmdlet has the following aliases, + \{\{Insert list of aliases\}\} + ## DESCRIPTION -A build script may declare a "Properies" function which allows you to define variables that will be available to all the "Task" functions in the build script. +A build script may declare a "Properties" function which allows you to +define variables that will be available within all the "Task" functions in +the build script. ## EXAMPLES ### EXAMPLE 1 -```powershell -A sample build script is shown below: -``` - Properties \{ $build_dir = "c:\build" $connection_string = "datasource=localhost;initial catalog=northwind;integrated security=sspi" \} - Task default -depends Test - Task Test -depends Compile, Clean \{ \} - Task Compile -depends Clean \{ \} - Task Clean \{ \} Note: You can have more than one "Properties" function defined in the build script. -## PARAMETERS +### EXAMPLE 2 -### -properties +Properties \{ + $script:build_dir = "c:\build" + $script:connection_string = "datasource=localhost;initial catalog=northwind;integrated security=sspi" +\} +Task Compile \{ + "Building to: $build_dir" # No PSScriptAnalyzer warning, variable is recognized +\} -The script block containing all the variable assignment statements +Recommended: Use script-scoped variables to avoid PSScriptAnalyzer warnings +The $script: prefix has identical runtime behavior but satisfies +PSScriptAnalyzer's static analysis requirements. -```yaml -Type: ScriptBlock -Parameter Sets: (All) -Aliases: +### EXAMPLE 3 -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` +Properties \{ + $build_dir = "c:\build" # Warning: PSUseDeclaredVarsMoreThanAssignments +\} +Task Compile \{ + "Building to: $build_dir" # Works at runtime, but PSScriptAnalyzer warns +\} + +Alternative: Non-scoped variables (generates PSScriptAnalyzer warnings) -### -ProgressAction +Variables still work correctly at runtime, but PSScriptAnalyzer cannot detect +that they will be used in tasks. + +## PARAMETERS -\{\{ Fill ProgressAction Description \}\} +### -Hashtable +An alternative to the scriptblock parameter, you can provide a hashtable of +key-value pairs that will be converted into variables. +This is useful when +you want to define properties programmatically or from an external source. + +```yaml +Type: System.Collections.Hashtable +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: Hashtable + Position: 0 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` ```yaml -Type: ActionPreference +Type: None Parameter Sets: (All) -Aliases: proga +Aliases: Required: False Position: Named @@ -89,10 +128,33 @@ Default value: None Accept pipeline input: False Accept wildcard characters: False ``` +### -Properties + +The script block containing all the variable assignment statements + +```yaml +Type: System.Management.Automation.ScriptBlock +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: ScriptBlock + Position: 0 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -100,28 +162,46 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## NOTES -## RELATED LINKS - -[Assert](Assert.mdx) +This works by defining a script block that is pushed onto the +$psake.Context.Peek().properties stack. +This allows the properties to be +accessed within all tasks in the build script. +This means that the variables defined in the script block will be +available in the scope of the tasks, but not in the global scope of the +build script. -[Exec](Exec.mdx) +PSScriptAnalyzer may warn about variables assigned but not used +(PSUseDeclaredVarsMoreThanAssignments) when variables are declared in +Properties blocks. +This is a false positive - the variables ARE used +in tasks when the Properties scriptblock is dot-sourced at runtime. -[FormatTaskName](FormatTaskName.mdx) +To suppress this warning, use script-scoped variables: -[Framework](Framework.mdx) - -[Get-PSakeScriptTasks](Get-PSakeScriptTasks.mdx) +Properties \{ + $script:build_dir = "c:\build" + $script:connection_string = "datasource=..." +\} -[Include](Include.mdx) +This has identical runtime behavior but satisfies PSScriptAnalyzer's +static analysis requirements. +See the examples above for more details. -[Invoke-psake](Invoke-psake.mdx) -[Task](Task.mdx) +## RELATED LINKS -[TaskSetup](TaskSetup.mdx) +\{\{ Fill in the related links here \}\} +```yaml +Type: None +Parameter Sets: (All) +Aliases: -[TaskTearDown](TaskTearDown.mdx) +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` ## VERSION - -*This page was generated using comment-based help in [Psake 4.9.0](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Task.mdx b/docs/commands/Task.mdx index 50f61f9..bd20bf3 100644 --- a/docs/commands/Task.mdx +++ b/docs/commands/Task.mdx @@ -24,46 +24,51 @@ Defines a build task to be executed by psake ### Normal (Default) -```powershell -Task [-name] [[-action] ] [[-preaction] ] [[-postaction] ] - [[-precondition] ] [[-postcondition] ] [-continueOnError] [[-depends] ] - [[-requiredVariables] ] [[-description] ] [[-alias] ] - [-ProgressAction ] [] +``` +Task [-Name] [[-Action] ] [-PreAction ] + [-PostAction ] [-PreCondition ] [-PostCondition ] + [-ContinueOnError] [-Depends ] [-RequiredVariables ] [-Description ] + [-Alias ] [] ``` ### SharedTask -```powershell -Task [-name] [[-action] ] [[-preaction] ] [[-postaction] ] - [[-precondition] ] [[-postcondition] ] [-continueOnError] [[-depends] ] - [[-requiredVariables] ] [[-description] ] [[-alias] ] [-FromModule] - [[-requiredVersion] ] [[-minimumVersion] ] [[-maximumVersion] ] - [[-lessThanVersion] ] [-ProgressAction ] [] +``` +Task [-Name] [[-Action] ] -FromModule [-PreAction ] + [-PostAction ] [-PreCondition ] [-PostCondition ] + [-ContinueOnError] [-Depends ] [-RequiredVariables ] [-Description ] + [-Alias ] [-RequiredVersion ] [-MinimumVersion ] [-MaximumVersion ] + [-LessThanVersion ] [] +``` + +### Declarative + +``` +Task [-Name] [[-Definition] ] [] ``` +## ALIASES + +This cmdlet has the following aliases, + \{\{Insert list of aliases\}\} + ## DESCRIPTION -This function creates a 'task' object that will be used by the psake engine to execute a build task. +This function creates a 'task' object that will be used by the psake engine +to execute a build task. Note: There must be at least one task called 'default' in the build script ## EXAMPLES ### EXAMPLE 1 -```powershell -A sample build script is shown below: -``` - Task default -Depends Test - Task Test -Depends Compile, Clean \{ "This is a test" \} - Task Compile -Depends Clean \{ "Compile" \} - Task Clean \{ "Clean" \} @@ -71,11 +76,13 @@ Task Clean \{ The 'default' task is required and should not contain an 'Action' parameter. It uses the 'Depends' parameter to specify that 'Test' is a dependency -The 'Test' task uses the 'Depends' parameter to specify that 'Compile' and 'Clean' are dependencies +The 'Test' task uses the 'Depends' parameter to specify that 'Compile' and +'Clean' are dependencies The 'Compile' task depends on the 'Clean' task. Note: -The 'Action' parameter is defaulted to the script block following the 'Clean' task. +The 'Action' parameter is defaulted to the script block following the +'Clean' task. An equivalent 'Test' task is shown below: @@ -106,80 +113,636 @@ Total: 00:00:00.0782496 ## PARAMETERS -### -name +### -Action -The name of the task +A scriptblock containing the statements to execute for the task. ```yaml -Type: String +Type: System.Management.Automation.ScriptBlock +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: SharedTask + Position: 1 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +- Name: Normal + Position: 1 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` +```yaml +Type: None Parameter Sets: (All) -Aliases: +Aliases: -Required: True -Position: 1 +Required: False +Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False ``` +### -Alias -### -action +An alternate name for the task. -A scriptblock containing the statements to execute for the task. +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: SharedTask + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +- Name: Normal + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` +```yaml +Type: None +Parameter Sets: (All) +Aliases: +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` +### -ContinueOnError + +If this switch parameter is set then the task will not cause the build to +fail when an exception is thrown by the task + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: False +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: SharedTask + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +- Name: Normal + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` ```yaml -Type: ScriptBlock +Type: None Parameter Sets: (All) -Aliases: +Aliases: Required: False -Position: 2 +Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False ``` +### -Definition + +A hashtable that can be used to define a task using a single parameter +instead of using multiple parameters. +This is an alternative to the normal +syntax of Task 'TaskName' -Action \{ ... +\} -Depends 'OtherTask' and allows +for a more declarative style of task definition. +The hashtable can contain +the following keys: +- Action +- PreAction +- PostAction +- PreCondition +- PostCondition -### -preaction +```yaml +Type: System.Collections.Hashtable +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: Declarative + Position: 1 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` +```yaml +Type: None +Parameter Sets: (All) +Aliases: -A scriptblock to be executed before the 'Action' scriptblock. -Note: This parameter is ignored if the 'Action' scriptblock is not defined. +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` +### -Depends + +An array of task names that this task depends on. +These tasks will be executed before the current task is executed. + +```yaml +Type: System.String[] +DefaultValue: '@()' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: SharedTask + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +- Name: Normal + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` +```yaml +Type: None +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` +### -Description + +A description of the task. ```yaml -Type: ScriptBlock +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: SharedTask + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +- Name: Normal + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` +```yaml +Type: None Parameter Sets: (All) -Aliases: +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` +### -FromModule + +Load in the task from the specified PowerShell module. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: SharedTask + Position: Named + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` +```yaml +Type: None +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` +### -LessThanVersion + +The version of the PowerShell module to load in the task from that should +not be met or exceeded. +eg -LessThanVersion 2.0.0 will reject anything 2.0.0 +or higher, allowing any module in the 1.x.x series. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: SharedTask + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` +```yaml +Type: None +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` +### -MaximumVersion + +The maximum (inclusive) version of the PowerShell module to load in the task +from. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: SharedTask + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` +```yaml +Type: None +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` +### -MinimumVersion + +The minimum (inclusive) version of the PowerShell module to load in the task +from. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: SharedTask + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` +```yaml +Type: None +Parameter Sets: (All) +Aliases: Required: False -Position: 3 +Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False ``` +### -Name -### -postaction +The name of the task + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` +```yaml +Type: None +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` +### -PostAction A scriptblock to be executed after the 'Action' scriptblock. Note: This parameter is ignored if the 'Action' scriptblock is not defined. ```yaml -Type: ScriptBlock +Type: System.Management.Automation.ScriptBlock +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: SharedTask + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +- Name: Normal + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` +```yaml +Type: None Parameter Sets: (All) -Aliases: +Aliases: Required: False -Position: 4 +Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False ``` +### -PostCondition + +A scriptblock that is executed to determine if the task completed its job +correctly. +An exception is thrown if the scriptblock returns $false. + +```yaml +Type: System.Management.Automation.ScriptBlock +DefaultValue: '{ $true }' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: SharedTask + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +- Name: Normal + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` +```yaml +Type: None +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` +### -PreAction + +A scriptblock to be executed before the 'Action' scriptblock. +Note: This parameter is ignored if the 'Action' scriptblock is not defined. + +```yaml +Type: System.Management.Automation.ScriptBlock +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: SharedTask + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +- Name: Normal + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` +```yaml +Type: None +Parameter Sets: (All) +Aliases: -### -precondition +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` +### -PreCondition -A scriptblock that is executed to determine if the task is executed or skipped. +A scriptblock that is executed to determine if the task is executed or +skipped. This scriptblock should return $true or $false ```yaml -Type: ScriptBlock +Type: System.Management.Automation.ScriptBlock +DefaultValue: '{ $true }' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: SharedTask + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +- Name: Normal + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` +```yaml +Type: None +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` +### -RequiredVariables + +An array of names of variables that must be set to run this task. + +```yaml +Type: System.String[] +DefaultValue: '@()' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: SharedTask + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +- Name: Normal + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` +```yaml +Type: None Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` +### -RequiredVersion + +The specific version of a module to load the task from + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false Aliases: +- Version +ParameterSets: +- Name: SharedTask + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES + +## RELATED LINKS + +\{\{ Fill in the related links here \}\} +```yaml +Type: None +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` -R +## VERSION +*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/TaskSetup.mdx b/docs/commands/TaskSetup.mdx index b8c4bc2..218960b 100644 --- a/docs/commands/TaskSetup.mdx +++ b/docs/commands/TaskSetup.mdx @@ -22,10 +22,17 @@ Adds a scriptblock that will be executed before each task ## SYNTAX -```powershell -TaskSetup [-setup] [-ProgressAction ] [] +### __AllParameterSets + +``` +TaskSetup [-Setup] [] ``` +## ALIASES + +This cmdlet has the following aliases, + \{\{Insert list of aliases\}\} + ## DESCRIPTION This function will accept a scriptblock that will be executed before each task in the build script. @@ -36,21 +43,13 @@ The scriptblock accepts an optional parameter which describes the Task being set ### EXAMPLE 1 -```powershell -A sample build script is shown below: -``` - -Task default -depends Test - -Task Test -depends Compile, Clean \{ +Task default -Depends Test +Task Test -Depends Compile, Clean \{ \} - -Task Compile -depends Clean \{ +Task Compile -Depends Clean \{ \} - Task Clean \{ \} - TaskSetup \{ "Running 'TaskSetup' for task $context.Peek().currentTaskName" \} @@ -68,25 +67,17 @@ Build Succeeded ### EXAMPLE 2 -```powershell -A sample build script showing access to the Task context is shown below: -``` - -Task default -depends Test - -Task Test -depends Compile, Clean \{ +Task default -Depends Test +Task Test -Depends Compile, Clean \{ \} - -Task Compile -depends Clean \{ +Task Compile -Depends Clean \{ \} - Task Clean \{ \} - TaskSetup \{ param($task) - "Running 'TaskSetup' for task $($task.Name)" +"Running 'TaskSetup' for task $($task.Name)" \} The script above produces the following output: @@ -102,41 +93,33 @@ Build Succeeded ## PARAMETERS -### -setup +### -Setup A scriptblock to execute ```yaml -Type: ScriptBlock -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -ProgressAction - -\{\{ Fill ProgressAction Description \}\} - -```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: proga - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False +Type: System.Management.Automation.ScriptBlock +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -146,26 +129,18 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -[Assert](Assert.mdx) - -[Exec](Exec.mdx) - -[FormatTaskName](FormatTaskName.mdx) - -[Framework](Framework.mdx) - -[Get-PSakeScriptTasks](Get-PSakeScriptTasks.mdx) - -[Include](Include.mdx) - -[Invoke-psake](Invoke-psake.mdx) - -[Properties](Properties.mdx) - -[Task](Task.mdx) +\{\{ Fill in the related links here \}\} +```yaml +Type: None +Parameter Sets: (All) +Aliases: -[TaskTearDown](TaskTearDown.mdx) +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` ## VERSION - -*This page was generated using comment-based help in [Psake 4.9.0](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/TaskTearDown.mdx b/docs/commands/TaskTearDown.mdx index 6e533b6..610a71f 100644 --- a/docs/commands/TaskTearDown.mdx +++ b/docs/commands/TaskTearDown.mdx @@ -22,39 +22,39 @@ Adds a scriptblock to the build that will be executed after each task ## SYNTAX -```powershell -TaskTearDown [-teardown] [-ProgressAction ] [] +### __AllParameterSets + +``` +TaskTearDown [-TearDown] [] ``` +## ALIASES + +This cmdlet has the following aliases, + \{\{Insert list of aliases\}\} + ## DESCRIPTION -This function will accept a scriptblock that will be executed after each task in the build script. +This function will accept a scriptblock that will be executed after each +task in the build script. -The scriptblock accepts an optional parameter which describes the Task being torn down. +The scriptblock accepts an optional parameter which describes the Task being +torn down. ## EXAMPLES ### EXAMPLE 1 -```powershell -A sample build script is shown below: -``` - -Task default -depends Test - -Task Test -depends Compile, Clean \{ +Task default -Depends Test +Task Test -Depends Compile, Clean \{ \} - -Task Compile -depends Clean \{ +Task Compile -Depends Clean \{ \} - Task Clean \{ \} - TaskTearDown \{ "Running 'TaskTearDown' for task $context.Peek().currentTaskName" \} - The script above produces the following output: Executing task, Clean... @@ -68,25 +68,17 @@ Build Succeeded ### EXAMPLE 2 -```powershell -A sample build script demonstrating access to the task context is shown below: -``` - -Task default -depends Test - -Task Test -depends Compile, Clean \{ +Task default -Depends Test +Task Test -Depends Compile, Clean \{ \} - -Task Compile -depends Clean \{ +Task Compile -Depends Clean \{ \} - Task Clean \{ \} - TaskTearDown \{ param($task) - if ($task.Success) \{ +if ($task.Success) \{ "Running 'TaskTearDown' for task $($task.Name) - success!" \} else \{ "Running 'TaskTearDown' for task $($task.Name) - failed: $($task.ErrorMessage)" @@ -106,41 +98,33 @@ Build Succeeded ## PARAMETERS -### -teardown +### -TearDown A scriptblock to execute ```yaml -Type: ScriptBlock -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -ProgressAction - -\{\{ Fill ProgressAction Description \}\} - -```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: proga - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False +Type: System.Management.Automation.ScriptBlock +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -150,26 +134,18 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -[Assert](Assert.mdx) - -[Exec](Exec.mdx) - -[FormatTaskName](FormatTaskName.mdx) - -[Framework](Framework.mdx) - -[Get-PSakeScriptTasks](Get-PSakeScriptTasks.mdx) - -[Include](Include.mdx) - -[Invoke-psake](Invoke-psake.mdx) - -[Properties](Properties.mdx) - -[Task](Task.mdx) +\{\{ Fill in the related links here \}\} +```yaml +Type: None +Parameter Sets: (All) +Aliases: -[TaskSetup](TaskSetup.mdx) +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` ## VERSION - -*This page was generated using comment-based help in [Psake 4.9.0](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Test-BuildEnvironment.mdx b/docs/commands/Test-BuildEnvironment.mdx index f30e2c1..e577f98 100644 --- a/docs/commands/Test-BuildEnvironment.mdx +++ b/docs/commands/Test-BuildEnvironment.mdx @@ -16,6 +16,10 @@ custom_edit_url: null Contributions are welcome in [Psake-repo](https://github.com/psake/psake). ::: +:::note Since Psake 5.0 +This command was introduced in Psake 5.0 and is not available in earlier versions. +::: + ## SYNOPSIS Tests whether the .NET framework required by a build is available on the @@ -25,16 +29,21 @@ current machine. ### Framework (Default) -```powershell -Test-BuildEnvironment [[-Framework] ] [-ProgressAction ] [] +``` +Test-BuildEnvironment [[-Framework] ] [] ``` ### BuildFile -```powershell -Test-BuildEnvironment -BuildFile [-ProgressAction ] [] +``` +Test-BuildEnvironment -BuildFile [] ``` +## ALIASES + +This cmdlet has the following aliases, + \{\{Insert list of aliases\}\} + ## DESCRIPTION Resolves the MSBuild and .NET runtime directories for the specified @@ -74,52 +83,28 @@ rest of test ### EXAMPLE 1 -```powershell Test-BuildEnvironment -Framework '4.8' -``` Returns $true when MSBuild 17.0 or 16.0 and the v4.0.30319 runtime directory are both present. ### EXAMPLE 2 -```powershell Test-BuildEnvironment -BuildFile './psakefile.ps1' -``` Loads the build file, reads its Framework setting, and returns $true if that framework is installed. ### EXAMPLE 3 -```powershell -if (-not (Test-BuildEnvironment)) { +if (-not (Test-BuildEnvironment)) \{ Write-Warning "Build environment not ready for current framework" -} -``` +\} Tests the framework configured in the active psake context. ## PARAMETERS -### -Framework - -The .NET framework version string to test (e.g. -'4.8', '3.5', '4.7.2x64'). -Takes precedence over -BuildFile and the active context. - -```yaml -Type: String -Parameter Sets: Framework -Aliases: - -Required: False -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - ### -BuildFile Path to a psake build script. @@ -128,25 +113,25 @@ and tested. Ignored when -Framework is also supplied. ```yaml -Type: String -Parameter Sets: BuildFile -Aliases: - -Required: True -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: BuildFile + Position: Named + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` - -### -ProgressAction - -\{\{ Fill ProgressAction Description \}\} - ```yaml -Type: ActionPreference +Type: None Parameter Sets: (All) -Aliases: proga +Aliases: Required: False Position: Named @@ -154,10 +139,35 @@ Default value: None Accept pipeline input: False Accept wildcard characters: False ``` +### -Framework + +The .NET framework version string to test (e.g. +'4.8', '3.5', '4.7.2x64'). +Takes precedence over -BuildFile and the active context. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: Framework + Position: 0 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -165,10 +175,28 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### [bool] +\{\{ Fill in the Description \}\} + +### System.Boolean + +\{\{ Fill in the Description \}\} + ## NOTES ## RELATED LINKS -## VERSION +\{\{ Fill in the related links here \}\} +```yaml +Type: None +Parameter Sets: (All) +Aliases: -*This page was generated using comment-based help in [Psake 5.0.2](https://github.com/psake/psake).* +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +## VERSION +*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Test-PsakeTask.mdx b/docs/commands/Test-PsakeTask.mdx index 91085a2..fdbb586 100644 --- a/docs/commands/Test-PsakeTask.mdx +++ b/docs/commands/Test-PsakeTask.mdx @@ -16,16 +16,27 @@ custom_edit_url: null Contributions are welcome in [Psake-repo](https://github.com/psake/psake). ::: +:::note Since Psake 5.0 +This command was introduced in Psake 5.0 and is not available in earlier versions. +::: + ## SYNOPSIS Runs a single task's Action in isolation, without triggering dependencies. ## SYNTAX -```powershell -Test-PsakeTask [[-BuildFile] ] [-TaskName] [[-Variables] ] - [-ProgressAction ] [] +### __AllParameterSets + ``` +Test-PsakeTask [[-BuildFile] ] [-TaskName] [[-Variables] ] + [] +``` + +## ALIASES + +This cmdlet has the following aliases, + \{\{Insert list of aliases\}\} ## DESCRIPTION @@ -38,13 +49,11 @@ executed.This enables unit-testing individual tasks. ### EXAMPLE 1 -```powershell -$result = Test-PsakeTask -BuildFile './psakefile.ps1' -TaskName 'Build' -Variables @{ +$result = Test-PsakeTask -BuildFile './psakefile.ps1' -TaskName 'Build' -Variables @\{ Configuration = 'Debug' OutputDir = './test-output' -} +\} $result.Success | Should -BeTrue -``` This example runs the 'Build' task from 'psakefile.ps1' with two variables injected into the task's scope. @@ -59,68 +68,90 @@ The path to the psake build script. Defaults to 'psakefile.ps1'. ```yaml -Type: String +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` +```yaml +Type: None Parameter Sets: (All) -Aliases: +Aliases: Required: False -Position: 1 +Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False ``` - ### -TaskName The name of the task to execute. ```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: True -Position: 2 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 1 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` - -### -Variables - -A hashtable of variables to inject into the task's execution scope. - ```yaml -Type: Hashtable +Type: None Parameter Sets: (All) -Aliases: +Aliases: Required: False -Position: 3 -Default value: @{} +Position: Named +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` +### -Variables -### -ProgressAction - -\{\{ Fill ProgressAction Description \}\} +A hashtable of variables to inject into the task's execution scope. ```yaml -Type: ActionPreference -Parameter Sets: (All) -Aliases: proga - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False +Type: System.Collections.Hashtable +DefaultValue: '@{}' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 2 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -133,8 +164,21 @@ dependencies or pre/post actions. It directly invokes the specified task's Action scriptblock in isolation. + ## RELATED LINKS -## VERSION +\{\{ Fill in the related links here \}\} +```yaml +Type: None +Parameter Sets: (All) +Aliases: -*This page was generated using comment-based help in [Psake 5.0.2](https://github.com/psake/psake).* +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +## VERSION +*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Version.mdx b/docs/commands/Version.mdx index 4844e5c..3395cdc 100644 --- a/docs/commands/Version.mdx +++ b/docs/commands/Version.mdx @@ -16,16 +16,27 @@ custom_edit_url: null Contributions are welcome in [Psake-repo](https://github.com/psake/psake). ::: +:::note Since Psake 5.0 +This command was introduced in Psake 5.0 and is not available in earlier versions. +::: + ## SYNOPSIS Declares the required psake version for the build script. ## SYNTAX -```powershell -Version [-RequiredVersion] [-ProgressAction ] [] +### __AllParameterSets + +``` +Version [-RequiredVersion] [] ``` +## ALIASES + +This cmdlet has the following aliases, + \{\{Insert list of aliases\}\} + ## DESCRIPTION Use this function at the top of a psake build script to declare which @@ -37,9 +48,7 @@ that the running psake version matches. ### EXAMPLE 1 -```powershell Version 5 -``` Declares that this build script requires psake v5. @@ -51,25 +60,42 @@ The major version number required (e.g. 5). ```yaml -Type: Int32 -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: 0 -Accept pipeline input: False -Accept wildcard characters: False +Type: System.Int32 +DefaultValue: 0 +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` -### -ProgressAction +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES -\{\{ Fill ProgressAction Description \}\} +## RELATED LINKS +\{\{ Fill in the related links here \}\} ```yaml -Type: ActionPreference +Type: None Parameter Sets: (All) -Aliases: proga +Aliases: Required: False Position: Named @@ -78,18 +104,5 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### CommonParameters - -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -## OUTPUTS - -## NOTES - -## RELATED LINKS - ## VERSION - -*This page was generated using comment-based help in [Psake 5.0.2](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/docusaurus.sidebar.js b/docs/commands/docusaurus.sidebar.js index 7b3e5f6..80a885a 100644 --- a/docs/commands/docusaurus.sidebar.js +++ b/docs/commands/docusaurus.sidebar.js @@ -1,7 +1,7 @@ /** * Import this file in your Docusaurus `sidebars.js` file. * - * Auto-generated by New-PsakeDocusaurusHelp using Microsoft.PowerShell.PlatyPS. + * Auto-generated by New-DocusaurusModuleHelp using Microsoft.PowerShell.PlatyPS. */ module.exports = [ @@ -15,7 +15,7 @@ module.exports = [ 'commands/Get-PsakeBuildPlan', 'commands/Get-PSakeScriptTasks', 'commands/Include', - 'commands/Invoke-psake', + 'commands/Invoke-Psake', 'commands/Invoke-Task', 'commands/Properties', 'commands/Task', @@ -23,5 +23,5 @@ module.exports = [ 'commands/TaskTearDown', 'commands/Test-BuildEnvironment', 'commands/Test-PsakeTask', - 'commands/Version', -]; + 'commands/Version' +]; \ No newline at end of file diff --git a/psakeFile.ps1 b/psakeFile.ps1 index d252ad7..44282d0 100644 --- a/psakeFile.ps1 +++ b/psakeFile.ps1 @@ -1,30 +1,24 @@ -#require -Version 7 +#requires -Version 7 Version 5 $ErrorView = 'Detailed' Properties { - $script:OutputPath = $null - $script:OutputFormat = 'Nunit' $script:psakeVersion = (Get-Module psake).Version + $script:PowerShellBuildVersion = (Get-Module PowerShellBuild).Version # ----------------------------------------------------------------------------- # Use below settings to manipulate the rendered MDX files # ----------------------------------------------------------------------------- $script:docusaurusOptions = @{ - Module = "Psake" - DocsFolder = "./docs" - SideBar = "commands" - EditUrl = "null" # prevent the `Edit this Page` button from appearing + Module = 'Psake' + DocsFolder = './docs' + SideBar = 'commands' + EditUrl = 'null' # prevent the `Edit this Page` button from appearing Exclude = @() MetaDescription = 'Help page for the PowerShell Psake "%1" command' - MetaKeywords = @( - "PowerShell" - "Psake" - "Help" - "Documentation" - ) + MetaKeywords = @('PowerShell', 'Psake', 'Help', 'Documentation') PrependMarkdown = @" :::info This page was generated Contributions are welcome in [Psake-repo](https://github.com/psake/psake). @@ -36,17 +30,17 @@ Contributions are welcome in [Psake-repo](https://github.com/psake/psake). "@ HelpVersion = "$($script:psakeVersion)" CommandVersionMap = @{ - 'BuildSetup' = '5.0' - 'BuildTearDown' = '5.0' - 'Clear-PsakeCache' = '5.0' - 'Execute' = '5.0' - 'Get-PsakeBuildPlan' = '5.0' + 'BuildSetup' = '5.0' + 'BuildTearDown' = '5.0' + 'Clear-PsakeCache' = '5.0' + 'Execute' = '5.0' + 'Get-PsakeBuildPlan' = '5.0' 'Test-BuildEnvironment' = '5.0' - 'Test-PsakeTask' = '5.0' - 'Version' = '5.0' + 'Test-PsakeTask' = '5.0' + 'Version' = '5.0' } } - $script:docsOutputFolder = Join-Path -Path $docusaurusOptions.DocsFolder -ChildPath $docusaurusOptions.Sidebar | Join-Path -ChildPath "*.*" + $script:docsOutputFolder = Join-Path $docusaurusOptions.DocsFolder $docusaurusOptions.Sidebar | Join-Path -ChildPath '*.*' # ----------------------------------------------------------------------------- # PowerShellBuild command reference options @@ -54,18 +48,13 @@ Contributions are welcome in [Psake-repo](https://github.com/psake/psake). $script:psbVersion = (Get-Module PowerShellBuild -ListAvailable | Sort-Object Version -Descending | Select-Object -First 1).Version $script:psbOptions = @{ - Module = "PowerShellBuild" - DocsFolder = "./docs" - SideBar = "psb-commands" - EditUrl = "null" + Module = 'PowerShellBuild' + DocsFolder = './docs' + SideBar = 'psb-commands' + EditUrl = 'null' Exclude = @() MetaDescription = 'Help page for the PowerShellBuild "%1" command' - MetaKeywords = @( - "PowerShell" - "PowerShellBuild" - "Help" - "Documentation" - ) + MetaKeywords = @('PowerShell', 'PowerShellBuild', 'Help', 'Documentation') PrependMarkdown = @" :::info This page was generated Contributions are welcome in [PowerShellBuild-repo](https://github.com/psake/PowerShellBuild). @@ -77,7 +66,7 @@ Contributions are welcome in [PowerShellBuild-repo](https://github.com/psake/Pow "@ HelpVersion = "$($script:psbVersion)" } - $script:psbOutputFolder = Join-Path -Path $psbOptions.DocsFolder -ChildPath $psbOptions.Sidebar | Join-Path -ChildPath "*.*" + $script:psbOutputFolder = Join-Path $psbOptions.DocsFolder $psbOptions.Sidebar | Join-Path -ChildPath '*.*' } FormatTaskName { @@ -90,36 +79,33 @@ Task Default -Depends Build Task 'Init' @{ Description = 'Install Node.js dependencies.' - Inputs = @('package.json', 'bun.lock') - Outputs = 'node_modules/.cache' - Action = { exec { bun install } } + Inputs = @('package.json', 'bun.lock') + Outputs = 'node_modules' + Action = { Exec { bun install } } } Task 'Build' @{ Description = 'Full production site build.' - DependsOn = @('Init', 'GenerateCommandReference', 'GenerateCommandReferencePSB', 'FrontMatterCMSSync') - Action = { exec { bun run build } } + DependsOn = @('Init', 'GenerateCommandReference', 'GenerateCommandReferencePSB', 'FrontMatterCMSSync') + Action = { Exec { bun run build } } } Task 'Server' @{ Description = 'Serve the production build locally.' - DependsOn = 'Build' - Action = { exec { bun run serve } } + DependsOn = 'Build' + Action = { Exec { bun run serve } } } Task 'Test' @{ Description = 'Run Pester tests to validate sidebar links.' - Action = { + Action = { Import-Module Pester -MinimumVersion '5.0' -Force $configuration = New-PesterConfiguration $configuration.Output.Verbosity = 'Detailed' $configuration.Run.PassThru = $true $configuration.Run.Path = "$PSScriptRoot\tests" - try { - $testResult = Invoke-Pester -Configuration $configuration -Verbose - } finally { - } + $testResult = Invoke-Pester -Configuration $configuration -Verbose if ($testResult.FailedCount -gt 0) { throw 'One or more Pester tests failed' @@ -127,91 +113,91 @@ Task 'Test' @{ } } -(Get-Content ".\package.json" | ConvertFrom-Json -AsHashtable).scripts.Keys | ForEach-Object { - $action = [scriptblock]::create("exec { bun run $($_) }") - $taskSplat = @{ - name = "bun_$($_)" - action = $action - depends = @('Init') - description = "Automatic: A script defined in your package.json" +(Get-Content '.\package.json' | ConvertFrom-Json -AsHashtable).scripts.Keys | ForEach-Object { + Task "bun_$($_)" @{ + Action = [scriptblock]::Create("exec { bun run $($_) }") + DependsOn = @('Init') + Description = 'Automatic: A script defined in your package.json' } - Task @taskSplat } #region Command Reference Generation Tasks -$taskSplat = @{ - description = "Use Microsoft.PowerShell.PlatyPS to generate command reference docs." - depends = 'GenerateCommandReference-Gen' +Task 'GenerateCommandReference' @{ + Description = 'Use Microsoft.PowerShell.PlatyPS to generate command reference docs.' + DependsOn = 'GenerateCommandReference-Gen' } -Task -Name 'GenerateCommandReference' @taskSplat -Task -Name 'GenerateCommandReference-Clean' -Action { - Write-Host "Removing existing MDX files" -ForegroundColor Magenta - if (Test-Path -Path $script:docsOutputFolder) { - Remove-Item -Path $script:docsOutputFolder +Task 'GenerateCommandReference-Clean' @{ + Action = { + Write-Host 'Removing existing MDX files' -ForegroundColor Magenta + if (Test-Path -Path $script:docsOutputFolder) { + Remove-Item -Path $script:docsOutputFolder + } } } -Task -Name "GenerateCommandReference-Gen" -Depends 'GenerateCommandReference-Clean' { - Write-Host "Generating new MDX files using Microsoft.PowerShell.PlatyPS" -ForegroundColor Magenta - . "$PSScriptRoot\scripts\New-DocusaurusModuleHelp.ps1" - Import-Module Microsoft.PowerShell.PlatyPS -Force - New-DocusaurusModuleHelp @docusaurusOptions +Task 'GenerateCommandReference-Gen' @{ + DependsOn = 'GenerateCommandReference-Clean' + Action = { + Write-Host 'Generating new MDX files using Microsoft.PowerShell.PlatyPS' -ForegroundColor Magenta + . "$PSScriptRoot\scripts\New-DocusaurusModuleHelp.ps1" + Import-Module Microsoft.PowerShell.PlatyPS -Force + New-DocusaurusModuleHelp @script:docusaurusOptions + } } #endregion Command Reference Generation Tasks #region PSB Command Reference Generation Tasks -$taskSplat = @{ - description = "Use Microsoft.PowerShell.PlatyPS to generate PowerShellBuild command reference docs." - depends = 'GenerateCommandReferencePSB-Gen' +Task 'GenerateCommandReferencePSB' @{ + Description = 'Use Microsoft.PowerShell.PlatyPS to generate PowerShellBuild command reference docs.' + DependsOn = 'GenerateCommandReferencePSB-Gen' + PreCondition = { $null -ne (Get-Module PowerShellBuild -ListAvailable | Select-Object -First 1) } } -Task -Name 'GenerateCommandReferencePSB' @taskSplat -Task -Name 'GenerateCommandReferencePSB-Clean' -Action { - Write-Host "Removing existing PSB MDX files" -ForegroundColor Magenta - if (Test-Path -Path $script:psbOutputFolder) { - Remove-Item -Path $script:psbOutputFolder +Task 'GenerateCommandReferencePSB-Clean' @{ + Action = { + Write-Host 'Removing existing PSB MDX files' -ForegroundColor Magenta + if (Test-Path -Path $script:psbOutputFolder) { + Remove-Item -Path $script:psbOutputFolder + } } } -Task -Name "GenerateCommandReferencePSB-Gen" -Depends 'GenerateCommandReferencePSB-Clean' { - Write-Host "Generating new PSB MDX files using Microsoft.PowerShell.PlatyPS" -ForegroundColor Magenta - New-Item -ItemType Directory -Path (Join-Path $psbOptions.DocsFolder $psbOptions.SideBar) -Force | Out-Null - . "$PSScriptRoot\scripts\New-DocusaurusModuleHelp.ps1" - Import-Module Microsoft.PowerShell.PlatyPS -Force - Import-Module PowerShellBuild -Force - New-DocusaurusModuleHelp @psbOptions +Task 'GenerateCommandReferencePSB-Gen' @{ + DependsOn = 'GenerateCommandReferencePSB-Clean' + Action = { + Write-Host 'Generating new PSB MDX files using Microsoft.PowerShell.PlatyPS' -ForegroundColor Magenta + New-Item -ItemType Directory -Path (Join-Path $psbOptions.DocsFolder $psbOptions.SideBar) -Force | Out-Null + . "$PSScriptRoot\scripts\New-DocusaurusModuleHelp.ps1" + Import-Module Microsoft.PowerShell.PlatyPS -Force + Import-Module PowerShellBuild -Force + New-DocusaurusModuleHelp @script:psbOptions + } } #endregion PSB Command Reference Generation Tasks #region Sync Front Matter Data -Task -Name 'FrontMatterCMSSync' { - ( - 'blog/authors.yml', - 'blog/tags.yml' - ) | ForEach-Object { - if (-not (Test-Path $_)) { - Write-Warning "File not found: $_" - return - } - $name = $_ -replace '\.yml$', '.choices.jsonc' - $outputFile = Join-Path -Path $PSScriptRoot -ChildPath (Split-Path -Path $name -Leaf) - - [array]$output = @( - @{ - "_comment" = "This file is auto-generated from $_ via a psake task" +Task 'FrontMatterCMSSync' @{ + Description = 'Sync Docusaurus YAML data to FrontMatter CMS-friendly choices.jsonc files.' + Inputs = @('blog/authors.yml', 'blog/tags.yml') + Outputs = @('authors.choices.jsonc', 'tags.choices.jsonc') + Action = { + @('blog/authors.yml', 'blog/tags.yml') | ForEach-Object { + if (-not (Test-Path $_)) { + Write-Warning "File not found: $_" + return } - ) - $yaml = Get-Content -Raw $_ | ConvertFrom-Yaml - foreach ($item in $yaml.Keys) { - $value = $yaml[$item] - if (-not $value.Contains('handle')) { - $value.Add('handle', $item) + $outputFile = Join-Path $PSScriptRoot (($_ -replace 'blog/', '') -replace '\.yml$', '.choices.jsonc') + + [array]$output = @(@{ '_comment' = "This file is auto-generated from $_ via a psake task" }) + $yaml = Get-Content -Raw $_ | ConvertFrom-Yaml + foreach ($item in $yaml.Keys) { + $value = $yaml[$item] + if (-not $value.Contains('handle')) { $value.Add('handle', $item) } + $output += $value } - $output += $value + Set-Content -Path $outputFile -Force -Value ($output | ConvertTo-Json -Depth 10) } - Set-Content -Path $outputFile -Force -Value ($output | ConvertTo-Json -Depth 10) } - # TODO: Add support to sync back from FrontMatter CMS to authors.json and tags.json -} -Description "Syncs Docusaurus JSON data from authors.json and tags.json to FrontMatter CMS friendly choices.json files." +} #endregion Sync Front Matter Data diff --git a/requirements.psd1 b/requirements.psd1 index fba0571..66ff277 100644 --- a/requirements.psd1 +++ b/requirements.psd1 @@ -9,7 +9,7 @@ } } 'psake' = @{ - Version = '5.0.3' + Version = 'latest' } 'Microsoft.PowerShell.PlatyPS' = @{ Version = 'latest' diff --git a/scripts/New-DocusaurusModuleHelp.ps1 b/scripts/New-DocusaurusModuleHelp.ps1 index 50477a9..6473fe5 100644 --- a/scripts/New-DocusaurusModuleHelp.ps1 +++ b/scripts/New-DocusaurusModuleHelp.ps1 @@ -14,7 +14,9 @@ function New-DocusaurusModuleHelp { [hashtable] $CommandVersionMap = @{} ) - Import-Module $Module -Force + if (-not (Get-Module $Module)) { + Import-Module $Module -Force + } $tempDir = Join-Path ([System.IO.Path]::GetTempPath()) "platyps_$(Get-Random)" New-Item -ItemType Directory -Path $tempDir | Out-Null diff --git a/scripts/New-PsakeDocusaurusHelp.ps1 b/scripts/New-PsakeDocusaurusHelp.ps1 deleted file mode 100644 index 3282921..0000000 --- a/scripts/New-PsakeDocusaurusHelp.ps1 +++ /dev/null @@ -1,229 +0,0 @@ -function New-PsakeDocusaurusHelp { - [CmdletBinding()] - param( - [Parameter(Mandatory)] [string] $Module, - [Parameter(Mandatory)] [string] $DocsFolder, - [Parameter(Mandatory)] [string] $SideBar, - [string] $EditUrl = 'null', - [string[]] $Exclude = @(), - [string] $MetaDescription = 'Help page for the PowerShell %1 command', - [string[]] $MetaKeywords = @('PowerShell', 'Help', 'Documentation'), - [string] $PrependMarkdown = '', - [string] $AppendMarkdown = '', - [string] $HelpVersion = '' - ) - - Import-Module $Module -Force - - $tempDir = Join-Path ([System.IO.Path]::GetTempPath()) "platyps_$(Get-Random)" - New-Item -ItemType Directory -Path $tempDir | Out-Null - - try { - New-MarkdownCommandHelp -ModuleInfo (Get-Module $Module) -OutputFolder $tempDir -Force | Out-Null - - $moduleSubDir = Join-Path $tempDir $Module - $mdFiles = Get-ChildItem -Path $moduleSubDir -Filter '*.md' | - Where-Object { $_.BaseName -notin $Exclude } | - Sort-Object BaseName - - $outputFolder = Join-Path $DocsFolder $SideBar - $allCommandNames = $mdFiles | Select-Object -ExpandProperty BaseName - $sidebarItems = [System.Collections.Generic.List[string]]::new() - - foreach ($mdFile in $mdFiles) { - $commandName = $mdFile.BaseName - $mdxContent = ConvertTo-DocusaurusMdx ` - -SourceFile $mdFile ` - -CommandName $commandName ` - -MetaDescription $MetaDescription ` - -MetaKeywords $MetaKeywords ` - -EditUrl $EditUrl ` - -PrependMarkdown $PrependMarkdown ` - -AppendMarkdown $AppendMarkdown ` - -AllCommandNames $allCommandNames - - $outputPath = Join-Path $outputFolder "$commandName.mdx" - Set-Content -Path $outputPath -Value $mdxContent -Encoding UTF8 -NoNewline - Write-Host " Generated: $commandName.mdx" - - $sidebarItems.Add("'$SideBar/$commandName'") - } - - $sidebarEntries = ($sidebarItems | ForEach-Object { " $_" }) -join ",`n" - $sidebarContent = @" -/** - * Import this file in your Docusaurus ``sidebars.js`` file. - * - * Auto-generated by New-PsakeDocusaurusHelp using Microsoft.PowerShell.PlatyPS. - */ - -module.exports = [ -$sidebarEntries -]; -"@ - $sidebarPath = Join-Path $outputFolder 'docusaurus.sidebar.js' - Set-Content -Path $sidebarPath -Value $sidebarContent -Encoding UTF8 -NoNewline - Write-Host " Generated: docusaurus.sidebar.js ($($sidebarItems.Count) commands)" - } - finally { - Remove-Item -Path $tempDir -Recurse -Force -ErrorAction SilentlyContinue - } -} - -function ConvertTo-DocusaurusMdx { - param( - [System.IO.FileInfo] $SourceFile, - [string] $CommandName, - [string] $MetaDescription, - [string[]] $MetaKeywords, - [string] $EditUrl, - [string] $PrependMarkdown, - [string] $AppendMarkdown, - [string[]] $AllCommandNames - ) - - $raw = Get-Content -Path $SourceFile.FullName -Raw - - # Strip PlatyPS v2 frontmatter block - $body = $raw -replace '(?s)^---.*?---\s*', '' - - # Strip the H1 title line PlatyPS emits - $body = $body -replace '(?m)^# .+\r?\n', '' - - # Convert markdown parameter tables to yaml fenced blocks - $body = Convert-ParameterTablesToYamlFences -Body $body - - # Fix RELATED LINKS: [Name]() -> [Name](Name.mdx) for known commands, strip unknown - foreach ($cmd in $AllCommandNames) { - $escaped = [regex]::Escape($cmd) - $body = $body -replace "\[$escaped\]\(\)", "[$cmd]($cmd.mdx)" - } - $body = $body -replace '\[([^\]]+)\]\(\)', '$1' - - # Escape curly braces outside code fences (required for MDX/JSX compatibility) - $body = Escape-CurlyBracesOutsideCodeFences -Body $body - - # Build Docusaurus frontmatter - $description = $MetaDescription -replace '%1', $CommandName - $keywordsYaml = ($MetaKeywords | ForEach-Object { " - $_" }) -join "`n" - $customEditUrl = if ($EditUrl -eq 'null') { 'null' } else { "$EditUrl/$CommandName.ps1" } - - $frontmatter = @" ---- -id: $CommandName -title: $CommandName -description: $description -keywords: -$keywordsYaml -hide_title: false -hide_table_of_contents: false -custom_edit_url: $customEditUrl ---- -"@ - - $parts = [System.Collections.Generic.List[string]]::new() - $parts.Add($frontmatter) - if ($PrependMarkdown) { $parts.Add($PrependMarkdown.Trim()) } - $parts.Add($body.Trim()) - if ($AppendMarkdown) { $parts.Add($AppendMarkdown.Trim()) } - - return ($parts -join "`n`n") + "`n" -} - -function Convert-ParameterTablesToYamlFences { - param([string] $Body) - - # Match each ### -ParameterName block through to the next ### - or end of PARAMETERS section - $result = [System.Text.RegularExpressions.Regex]::Replace( - $Body, - '(?ms)(### -\w[^\r\n]*\r?\n)(.*?)(?=### -|\z)', - { - param($match) - $header = $match.Groups[1].Value - $content = $match.Groups[2].Value - - # Extract description text (everything before the first table row) - $descText = ($content -split '(?m)^\|')[0].TrimEnd() - - # Helper: extract a value from a markdown table row by property name - function Get-TableValue([string]$text, [string]$prop) { - if ($text -match "(?m)^\|\s*$([regex]::Escape($prop))\s*\|\s*([^|]+)\|") { - return $matches[1].Trim() - } - return $null - } - - $type = Get-TableValue $content 'Type:' - $mandatory = Get-TableValue $content 'Mandatory:' - $position = Get-TableValue $content 'Position:' - $default = Get-TableValue $content 'Default value:' - $pipeline = Get-TableValue $content 'Value from pipeline:' - $wildcard = Get-TableValue $content 'Supports wildcards:' - $aliases = Get-TableValue $content 'Aliases:' - - # Strip System. namespace prefix from types - if ($type) { $type = $type -replace '^System\.', '' } else { $type = 'None' } - - $required = if ($mandatory -eq 'True') { 'True' } else { 'False' } - - # v2 position is 0-based; v1 (target) is 1-based - if ($position -and $position -match '^\d+$') { - $position = [int]$position + 1 - } elseif (-not $position) { - $position = 'Named' - } - - if (-not $default) { $default = 'None' } - if (-not $pipeline) { $pipeline = 'False' } - if (-not $wildcard) { $wildcard = 'False' } - if (-not $aliases) { $aliases = '' } - - # Detect parameter sets - look for "Parameter sets" section in the content - $paramSets = '(All)' - if ($content -match '(?ms)Parameter sets\s*\r?\n\|[^\r\n]+\r?\n\|[^\r\n]+\r?\n\|\s*([^|]+)\|') { - $paramSets = $matches[1].Trim() - } - - $yamlFence = @" - -``````yaml -Type: $type -Parameter Sets: $paramSets -Aliases: $aliases - -Required: $required -Position: $position -Default value: $default -Accept pipeline input: $pipeline -Accept wildcard characters: $wildcard -`````` - -"@ - return $header + $descText + $yamlFence - } - ) - - return $result -} - -function Escape-CurlyBracesOutsideCodeFences { - param([string] $Body) - - # Split on fenced code blocks (``` delimiters), alternating outside/inside - $segments = [System.Text.RegularExpressions.Regex]::Split( - $Body, - '((?ms)^```[^\r\n]*\r?\n.*?^```\r?\n?)' - ) - - $result = for ($i = 0; $i -lt $segments.Count; $i++) { - if ($i % 2 -eq 0) { - # Outside a code fence — escape curly braces - $segments[$i] -replace '\{', '\{' -replace '\}', '\}' - } else { - # Inside a code fence — pass through unchanged - $segments[$i] - } - } - - return $result -join '' -} From 45414f7ba6156b6c677aeb529489801481ba5c00 Mon Sep 17 00:00:00 2001 From: Gilbert Sanchez Date: Tue, 28 Apr 2026 12:08:03 -0700 Subject: [PATCH 06/11] Fix Docusaurus build: broken links and PlatyPS v2 yaml format - docusaurus.config.ts: fix navbar link Invoke-psake -> Invoke-Psake (case) - docs/intro.md, docs/tutorial-basics/getting-help.md: same case fix - New-DocusaurusModuleHelp: skip Convert-ParameterTablesToYamlFences when PlatyPS v2 native yaml blocks are present (avoids duplicate yaml and stray blocks bleeding into RELATED LINKS section) - requirements.psd1: add Import=\$false for Pester to prevent PSDepend from reimporting already-loaded assemblies on CI (fixes 'Assembly with same name is already loaded' bootstrap failure) - Regenerate all 19 command reference MDX files Co-Authored-By: Claude Sonnet 4.6 --- docs/commands/Assert.mdx | 23 +-- docs/commands/BuildSetup.mdx | 11 -- docs/commands/BuildTearDown.mdx | 11 -- docs/commands/Clear-PsakeCache.mdx | 23 +-- docs/commands/Execute.mdx | 83 +--------- docs/commands/FormatTaskName.mdx | 11 -- docs/commands/Framework.mdx | 11 -- docs/commands/Get-PSakeScriptTasks.mdx | 11 -- docs/commands/Get-PsakeBuildPlan.mdx | 23 +-- docs/commands/Include.mdx | 23 +-- docs/commands/Invoke-Task.mdx | 11 -- docs/commands/Invoke-psake.mdx | 179 ++------------------- docs/commands/Properties.mdx | 23 +-- docs/commands/Task.mdx | 203 ++---------------------- docs/commands/TaskSetup.mdx | 11 -- docs/commands/TaskTearDown.mdx | 11 -- docs/commands/Test-BuildEnvironment.mdx | 23 +-- docs/commands/Test-PsakeTask.mdx | 35 +--- docs/commands/Version.mdx | 11 -- docs/intro.md | 2 +- docs/tutorial-basics/getting-help.md | 2 +- docusaurus.config.ts | 2 +- requirements.psd1 | 1 + scripts/New-DocusaurusModuleHelp.ps1 | 8 +- 24 files changed, 55 insertions(+), 697 deletions(-) diff --git a/docs/commands/Assert.mdx b/docs/commands/Assert.mdx index 1df5a7b..0ae0e66 100644 --- a/docs/commands/Assert.mdx +++ b/docs/commands/Assert.mdx @@ -87,17 +87,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -FailureMessage The error message used for the exception if the ConditionToCheck parameter is false @@ -135,17 +125,6 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS \{\{ Fill in the related links here \}\} -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` ## VERSION *This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/BuildSetup.mdx b/docs/commands/BuildSetup.mdx index 411c152..8ca34d2 100644 --- a/docs/commands/BuildSetup.mdx +++ b/docs/commands/BuildSetup.mdx @@ -103,17 +103,6 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS \{\{ Fill in the related links here \}\} -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` ## VERSION *This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/BuildTearDown.mdx b/docs/commands/BuildTearDown.mdx index 5cdcdcc..328f093 100644 --- a/docs/commands/BuildTearDown.mdx +++ b/docs/commands/BuildTearDown.mdx @@ -125,17 +125,6 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS \{\{ Fill in the related links here \}\} -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` ## VERSION *This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Clear-PsakeCache.mdx b/docs/commands/Clear-PsakeCache.mdx index 1ec5ddc..debf9fd 100644 --- a/docs/commands/Clear-PsakeCache.mdx +++ b/docs/commands/Clear-PsakeCache.mdx @@ -80,17 +80,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -TaskName Optional: clear cache for a specific task only. @@ -128,17 +118,6 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS - [Invoke-Psake](Invoke-Psake.mdx) -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` ## VERSION *This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Execute.mdx b/docs/commands/Execute.mdx index 3f9fd20..08ba444 100644 --- a/docs/commands/Execute.mdx +++ b/docs/commands/Execute.mdx @@ -80,17 +80,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -ErrorMessage The error message to display if the external command returned a non-zero @@ -112,17 +102,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -MaxRetries The maximum number of times to retry the command before failing. @@ -143,17 +123,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -NewProcess If set, the command will be executed in a new process. @@ -176,17 +146,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -RetryTriggerErrorPattern If the external command raises an exception, match the exception against @@ -210,17 +170,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -TimeoutSeconds If set, the command will be terminated if it runs longer than this number of @@ -243,17 +193,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -WorkingDirectory The working directory to set before running the external command. @@ -292,17 +232,6 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS \{\{ Fill in the related links here \}\} -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` ## VERSION *This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/FormatTaskName.mdx b/docs/commands/FormatTaskName.mdx index bbc0f8f..995e41f 100644 --- a/docs/commands/FormatTaskName.mdx +++ b/docs/commands/FormatTaskName.mdx @@ -137,17 +137,6 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS \{\{ Fill in the related links here \}\} -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` ## VERSION *This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Framework.mdx b/docs/commands/Framework.mdx index bd53aaa..b5fa96e 100644 --- a/docs/commands/Framework.mdx +++ b/docs/commands/Framework.mdx @@ -94,17 +94,6 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS \{\{ Fill in the related links here \}\} -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` ## VERSION *This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Get-PSakeScriptTasks.mdx b/docs/commands/Get-PSakeScriptTasks.mdx index 3aab1d8..032f13b 100644 --- a/docs/commands/Get-PSakeScriptTasks.mdx +++ b/docs/commands/Get-PSakeScriptTasks.mdx @@ -91,17 +91,6 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS \{\{ Fill in the related links here \}\} -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` ## VERSION *This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Get-PsakeBuildPlan.mdx b/docs/commands/Get-PsakeBuildPlan.mdx index ff9e68e..d14f014 100644 --- a/docs/commands/Get-PsakeBuildPlan.mdx +++ b/docs/commands/Get-PsakeBuildPlan.mdx @@ -104,17 +104,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -TaskList A list of task names to include in the plan. @@ -153,17 +143,6 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS \{\{ Fill in the related links here \}\} -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` ## VERSION *This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Include.mdx b/docs/commands/Include.mdx index e839495..494f5ae 100644 --- a/docs/commands/Include.mdx +++ b/docs/commands/Include.mdx @@ -95,17 +95,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -Path A string containing the path and name of the powershell file to include @@ -149,17 +139,6 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS \{\{ Fill in the related links here \}\} -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` ## VERSION *This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Invoke-Task.mdx b/docs/commands/Invoke-Task.mdx index 9b1508c..ae18786 100644 --- a/docs/commands/Invoke-Task.mdx +++ b/docs/commands/Invoke-Task.mdx @@ -85,17 +85,6 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS \{\{ Fill in the related links here \}\} -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` ## VERSION *This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Invoke-psake.mdx b/docs/commands/Invoke-psake.mdx index 5762f6e..1b7080c 100644 --- a/docs/commands/Invoke-psake.mdx +++ b/docs/commands/Invoke-psake.mdx @@ -103,17 +103,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -BuildPlan A pre-compiled [PsakeBuildPlan] to execute, typically from Get-PsakeBuildPlan @@ -138,17 +128,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -CompileOnly Return the build plan without executing any tasks. @@ -172,17 +152,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -DetailedDocs Prints a more descriptive list of tasks and their descriptions. @@ -203,17 +173,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -Docs Prints a list of tasks and their descriptions @@ -234,17 +194,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -Framework The version of the .NET framework you want to use during build. @@ -272,17 +222,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -Initialization A script block that will be executed before the tasks are executed. @@ -304,17 +244,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -NoCache Bypass task caching. @@ -336,17 +266,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -NoLogo Do not display the startup banner and copyright message. @@ -367,17 +287,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -NoTimeReport Do not display the time report. @@ -399,17 +309,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -OutputFormat The output format. @@ -434,17 +334,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -Parameters A hashtable containing parameters to be passed into the current build @@ -468,17 +358,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -Properties A hashtable containing properties to be passed into the current build @@ -502,17 +382,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -Quiet Suppress all console output. @@ -534,17 +404,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -TaskList A comma-separated list of task names to execute @@ -586,17 +446,6 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS \{\{ Fill in the related links here \}\} -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` ## VERSION *This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Properties.mdx b/docs/commands/Properties.mdx index 6678fb1..16a74cc 100644 --- a/docs/commands/Properties.mdx +++ b/docs/commands/Properties.mdx @@ -117,17 +117,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -Properties The script block containing all the variable assignment statements @@ -191,17 +181,6 @@ See the examples above for more details. ## RELATED LINKS \{\{ Fill in the related links here \}\} -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` ## VERSION *This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Task.mdx b/docs/commands/Task.mdx index bd20bf3..970a135 100644 --- a/docs/commands/Task.mdx +++ b/docs/commands/Task.mdx @@ -139,17 +139,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -Alias An alternate name for the task. @@ -176,17 +166,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -ContinueOnError If this switch parameter is set then the task will not cause the build to @@ -214,17 +194,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -Definition A hashtable that can be used to define a task using a single parameter @@ -257,17 +227,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -Depends An array of task names that this task depends on. @@ -295,17 +255,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -Description A description of the task. @@ -332,17 +282,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -FromModule Load in the task from the specified PowerShell module. @@ -363,17 +303,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -LessThanVersion The version of the PowerShell module to load in the task from that should @@ -397,17 +327,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -MaximumVersion The maximum (inclusive) version of the PowerShell module to load in the task @@ -429,17 +349,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -MinimumVersion The minimum (inclusive) version of the PowerShell module to load in the task @@ -461,17 +371,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -Name The name of the task @@ -492,17 +392,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -PostAction A scriptblock to be executed after the 'Action' scriptblock. @@ -530,17 +420,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -PostCondition A scriptblock that is executed to determine if the task completed its job @@ -569,17 +449,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -PreAction A scriptblock to be executed before the 'Action' scriptblock. @@ -607,17 +477,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -PreCondition A scriptblock that is executed to determine if the task is executed or @@ -646,17 +506,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -RequiredVariables An array of names of variables that must be set to run this task. @@ -683,17 +533,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -RequiredVersion The specific version of a module to load the task from @@ -732,17 +572,6 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS \{\{ Fill in the related links here \}\} -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` ## VERSION *This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/TaskSetup.mdx b/docs/commands/TaskSetup.mdx index 218960b..752d1e5 100644 --- a/docs/commands/TaskSetup.mdx +++ b/docs/commands/TaskSetup.mdx @@ -130,17 +130,6 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS \{\{ Fill in the related links here \}\} -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` ## VERSION *This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/TaskTearDown.mdx b/docs/commands/TaskTearDown.mdx index 610a71f..32ddfe7 100644 --- a/docs/commands/TaskTearDown.mdx +++ b/docs/commands/TaskTearDown.mdx @@ -135,17 +135,6 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS \{\{ Fill in the related links here \}\} -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` ## VERSION *This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Test-BuildEnvironment.mdx b/docs/commands/Test-BuildEnvironment.mdx index e577f98..0df2b49 100644 --- a/docs/commands/Test-BuildEnvironment.mdx +++ b/docs/commands/Test-BuildEnvironment.mdx @@ -128,17 +128,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -Framework The .NET framework version string to test (e.g. @@ -186,17 +176,6 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS \{\{ Fill in the related links here \}\} -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` ## VERSION *This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Test-PsakeTask.mdx b/docs/commands/Test-PsakeTask.mdx index fdbb586..c8df2c5 100644 --- a/docs/commands/Test-PsakeTask.mdx +++ b/docs/commands/Test-PsakeTask.mdx @@ -83,17 +83,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -TaskName The name of the task to execute. @@ -114,17 +104,7 @@ DontShow: false AcceptedValues: [] HelpMessage: '' ``` -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` + ### -Variables A hashtable of variables to inject into the task's execution scope. @@ -168,17 +148,6 @@ Action scriptblock in isolation. ## RELATED LINKS \{\{ Fill in the related links here \}\} -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` ## VERSION *This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Version.mdx b/docs/commands/Version.mdx index 3395cdc..f5667ea 100644 --- a/docs/commands/Version.mdx +++ b/docs/commands/Version.mdx @@ -92,17 +92,6 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS \{\{ Fill in the related links here \}\} -```yaml -Type: None -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` ## VERSION *This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/intro.md b/docs/intro.md index 2424d94..520996f 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -108,6 +108,6 @@ Ready to start using psake? Here's what to do next: 1. **[Install psake](/docs/tutorial-basics/installing)** - Get psake set up on your system 2. **[Run your first build](/docs/tutorial-basics/run-psake)** - Create and execute your first psake script 3. **[Explore the Guides](/docs/tutorial-basics/default-build-files)** - Learn best practices and advanced techniques -4. **[Check the Command Reference](/docs/commands/Invoke-psake)** - Look up specific commands and their parameters +4. **[Check the Command Reference](/docs/commands/Invoke-Psake)** - Look up specific commands and their parameters Need help? Visit our [Troubleshooting](/docs/troubleshooting/common-errors) section or join the [PowerShell Discord](https://aka.ms/psdiscord) #psake channel. diff --git a/docs/tutorial-basics/getting-help.md b/docs/tutorial-basics/getting-help.md index 4c851ff..341abbb 100644 --- a/docs/tutorial-basics/getting-help.md +++ b/docs/tutorial-basics/getting-help.md @@ -95,6 +95,6 @@ Found a bug or have a feature request? For comprehensive guides and reference materials: -- **[Command Reference](/docs/commands/Invoke-psake)** - Detailed documentation for all psake commands +- **[Command Reference](/docs/commands/Invoke-Psake)** - Detailed documentation for all psake commands - **[Troubleshooting](/docs/troubleshooting/common-errors)** - Solutions to common problems - **[FAQ](/docs/troubleshooting/faq)** - Frequently asked questions diff --git a/docusaurus.config.ts b/docusaurus.config.ts index dd50cf5..8b417a6 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -143,7 +143,7 @@ const config: Config = { }, { label: 'Command Reference', - to: '/docs/commands/Invoke-psake', + to: '/docs/commands/Invoke-Psake', }, { label: 'Code of Conduct', diff --git a/requirements.psd1 b/requirements.psd1 index 66ff277..e18ec42 100644 --- a/requirements.psd1 +++ b/requirements.psd1 @@ -7,6 +7,7 @@ Parameters = @{ SkipPublisherCheck = $true } + Import = $false } 'psake' = @{ Version = 'latest' diff --git a/scripts/New-DocusaurusModuleHelp.ps1 b/scripts/New-DocusaurusModuleHelp.ps1 index 6473fe5..331658d 100644 --- a/scripts/New-DocusaurusModuleHelp.ps1 +++ b/scripts/New-DocusaurusModuleHelp.ps1 @@ -150,7 +150,13 @@ custom_edit_url: $customEditUrl function Convert-ParameterTablesToYamlFences { param([string] $Body) - # Match each ### -ParameterName block through to the next ### - or end of PARAMETERS section + # PlatyPS v2 emits yaml fenced blocks natively (keys: DefaultValue, ParameterSets, etc.) + # These are already renderable — return body unchanged and skip table conversion. + if ($Body -match '(?ms)^```yaml[\r\n]+(?:Type|DefaultValue):') { + return $Body + } + + # PlatyPS v1: convert markdown tables to yaml fences $result = [System.Text.RegularExpressions.Regex]::Replace( $Body, '(?ms)(### -\w[^\r\n]*\r?\n)(.*?)(?=### -|\z)', From 357810a946c4911d3205e45c61ffe55b56611368 Mon Sep 17 00:00:00 2001 From: Gilbert Sanchez Date: Tue, 28 Apr 2026 12:41:25 -0700 Subject: [PATCH 07/11] Fix related links and param yaml: absolute URLs, splatting, PlatyPS v2 passthrough MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Switch RELATED LINKS generation from relative .mdx paths to absolute URL paths (/docs//) — avoids Linux case-sensitivity issues with git-tracked filename (Invoke-psake.mdx vs Invoke-Psake.mdx) - Rename git-tracked docs/commands/Invoke-psake.mdx -> Invoke-Psake.mdx (correct case) - Replace backtick line continuation with splat in ConvertTo-DocusaurusMdx call - Regenerate all 19 MDX files; local bun build passes with no broken links Co-Authored-By: Claude Sonnet 4.6 --- docs/commands/Clear-PsakeCache.mdx | 2 +- .../{Invoke-psake.mdx => Invoke-Psake.mdx} | 0 scripts/New-DocusaurusModuleHelp.ps1 | 30 +++++++++++-------- 3 files changed, 18 insertions(+), 14 deletions(-) rename docs/commands/{Invoke-psake.mdx => Invoke-Psake.mdx} (100%) diff --git a/docs/commands/Clear-PsakeCache.mdx b/docs/commands/Clear-PsakeCache.mdx index debf9fd..7ec9e64 100644 --- a/docs/commands/Clear-PsakeCache.mdx +++ b/docs/commands/Clear-PsakeCache.mdx @@ -117,7 +117,7 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -- [Invoke-Psake](Invoke-Psake.mdx) +- [Invoke-Psake](/docs/commands/Invoke-Psake) ## VERSION *This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Invoke-psake.mdx b/docs/commands/Invoke-Psake.mdx similarity index 100% rename from docs/commands/Invoke-psake.mdx rename to docs/commands/Invoke-Psake.mdx diff --git a/scripts/New-DocusaurusModuleHelp.ps1 b/scripts/New-DocusaurusModuleHelp.ps1 index 331658d..10469ba 100644 --- a/scripts/New-DocusaurusModuleHelp.ps1 +++ b/scripts/New-DocusaurusModuleHelp.ps1 @@ -46,16 +46,19 @@ This command was introduced in $Module $sinceVersion and is not available in ear "@ } - $mdxContent = ConvertTo-DocusaurusMdx ` - -SourceFile $mdFile ` - -CommandName $commandName ` - -MetaDescription $MetaDescription ` - -MetaKeywords $MetaKeywords ` - -EditUrl $EditUrl ` - -PrependMarkdown $PrependMarkdown ` - -AppendMarkdown $AppendMarkdown ` - -AllCommandNames $allCommandNames ` - -SinceBadge $sinceBadge + $mdxSplat = @{ + SourceFile = $mdFile + CommandName = $commandName + MetaDescription = $MetaDescription + MetaKeywords = $MetaKeywords + EditUrl = $EditUrl + PrependMarkdown = $PrependMarkdown + AppendMarkdown = $AppendMarkdown + AllCommandNames = $allCommandNames + SinceBadge = $sinceBadge + SideBar = $SideBar + } + $mdxContent = ConvertTo-DocusaurusMdx @mdxSplat $outputPath = Join-Path $outputFolder "$commandName.mdx" Set-Content -Path $outputPath -Value $mdxContent -Encoding UTF8 -NoNewline @@ -95,7 +98,8 @@ function ConvertTo-DocusaurusMdx { [string] $PrependMarkdown, [string] $AppendMarkdown, [string[]] $AllCommandNames, - [string] $SinceBadge = '' + [string] $SinceBadge = '', + [string] $SideBar = 'commands' ) $raw = Get-Content -Path $SourceFile.FullName -Raw @@ -109,10 +113,10 @@ function ConvertTo-DocusaurusMdx { # Convert markdown parameter tables to yaml fenced blocks $body = Convert-ParameterTablesToYamlFences -Body $body - # Fix RELATED LINKS: [Name]() -> [Name](Name.mdx) for known commands, strip unknown + # Fix RELATED LINKS: [Name]() -> [Name](/docs//Name) for known commands, strip unknown foreach ($cmd in $AllCommandNames) { $escaped = [regex]::Escape($cmd) - $body = $body -replace "\[$escaped\]\(\)", "[$cmd]($cmd.mdx)" + $body = $body -replace "\[$escaped\]\(\)", "[$cmd](/docs/$SideBar/$cmd)" } $body = $body -replace '\[([^\]]+)\]\(\)', '$1' From e91a588a9d059e6232d59859535903082604488b Mon Sep 17 00:00:00 2001 From: Gilbert Sanchez Date: Tue, 28 Apr 2026 12:53:00 -0700 Subject: [PATCH 08/11] Wrap example code in powershell fenced blocks during MDX generation PlatyPS v2 changed from v1 behavior: example code is now emitted as plain text instead of fenced code blocks. Detect the first paragraph of each ### EXAMPLE section and wrap it in ```powershell fences. The guard (?!```) prevents double-wrapping if a fence is already present. Issue is in PlatyPS v2 export behavior, not in psake CBH (which correctly uses C:\PS> prompt prefix convention that PlatyPS strips). Co-Authored-By: Claude Sonnet 4.6 --- docs/commands/Assert.mdx | 6 ++++ docs/commands/BuildSetup.mdx | 19 +++++++----- docs/commands/BuildTearDown.mdx | 38 +++++++++++++---------- docs/commands/Clear-PsakeCache.mdx | 6 ++++ docs/commands/Execute.mdx | 5 ++- docs/commands/FormatTaskName.mdx | 6 ++++ docs/commands/Framework.mdx | 7 +++-- docs/commands/Get-PSakeScriptTasks.mdx | 3 ++ docs/commands/Get-PsakeBuildPlan.mdx | 9 ++++++ docs/commands/Include.mdx | 18 +++++++---- docs/commands/Invoke-Psake.mdx | 15 +++++++++ docs/commands/Invoke-Task.mdx | 3 ++ docs/commands/Properties.mdx | 41 +++++++++++++++---------- docs/commands/Task.mdx | 15 +++++---- docs/commands/TaskSetup.mdx | 36 +++++++++++++--------- docs/commands/TaskTearDown.mdx | 36 +++++++++++++--------- docs/commands/Test-BuildEnvironment.mdx | 13 ++++++-- docs/commands/Test-PsakeTask.mdx | 7 +++-- docs/commands/Version.mdx | 3 ++ scripts/New-DocusaurusModuleHelp.ps1 | 14 +++++++++ 20 files changed, 211 insertions(+), 89 deletions(-) diff --git a/docs/commands/Assert.mdx b/docs/commands/Assert.mdx index 0ae0e66..eeecf70 100644 --- a/docs/commands/Assert.mdx +++ b/docs/commands/Assert.mdx @@ -41,13 +41,19 @@ This is a helper function that makes the code less noisy by eliminating many of ### EXAMPLE 1 +```powershell Assert $false "This always throws an exception" +``` + Example of an assertion that will always fail. ### EXAMPLE 2 +```powershell Assert ( ($i % 2) -eq 0 ) "$i is not an even number" +``` + This exmaple may throw an exception if $i is not an even number diff --git a/docs/commands/BuildSetup.mdx b/docs/commands/BuildSetup.mdx index 8ca34d2..ac5a8a5 100644 --- a/docs/commands/BuildSetup.mdx +++ b/docs/commands/BuildSetup.mdx @@ -46,16 +46,19 @@ beginning of the build. ### EXAMPLE 1 +```powershell Task default -Depends Test -Task Test -Depends Compile, Clean \{ -\} -Task Compile -Depends Clean \{ -\} -Task Clean \{ -\} -BuildSetup \{ +Task Test -Depends Compile, Clean { +} +Task Compile -Depends Clean { +} +Task Clean { +} +BuildSetup { "Running 'BuildSetup'" -\} +} +``` + The script above produces the following output: Running 'BuildSetup' diff --git a/docs/commands/BuildTearDown.mdx b/docs/commands/BuildTearDown.mdx index 328f093..daa968b 100644 --- a/docs/commands/BuildTearDown.mdx +++ b/docs/commands/BuildTearDown.mdx @@ -46,16 +46,19 @@ end of the build, regardless of success or failure ### EXAMPLE 1 +```powershell Task default -Depends Test -Task Test -Depends Compile, Clean \{ -\} -Task Compile -Depends Clean \{ -\} -Task Clean \{ -\} -BuildTearDown \{ +Task Test -Depends Compile, Clean { +} +Task Compile -Depends Clean { +} +Task Clean { +} +BuildTearDown { "Running 'BuildTearDown'" -\} +} +``` + The script above produces the following output: Executing task, Clean... @@ -66,17 +69,20 @@ Build Succeeded ### EXAMPLE 2 +```powershell Task default -Depends Test -Task Test -Depends Compile, Clean \{ +Task Test -Depends Compile, Clean { throw "forced error" -\} -Task Compile -Depends Clean \{ -\} -Task Clean \{ -\} -BuildTearDown \{ +} +Task Compile -Depends Clean { +} +Task Clean { +} +BuildTearDown { "Running 'BuildTearDown'" -\} +} +``` + The script above produces the following output: Executing task, Clean... diff --git a/docs/commands/Clear-PsakeCache.mdx b/docs/commands/Clear-PsakeCache.mdx index 7ec9e64..218b210 100644 --- a/docs/commands/Clear-PsakeCache.mdx +++ b/docs/commands/Clear-PsakeCache.mdx @@ -46,13 +46,19 @@ This forces all tasks to re-execute on the next build. ### EXAMPLE 1 +```powershell Clear-PsakeCache +``` + Clears all cached task state in the current directory. ### EXAMPLE 2 +```powershell Clear-PsakeCache -TaskName 'Build' +``` + Clears cached state for the 'Build' task only. diff --git a/docs/commands/Execute.mdx b/docs/commands/Execute.mdx index 08ba444..20e93cd 100644 --- a/docs/commands/Execute.mdx +++ b/docs/commands/Execute.mdx @@ -52,7 +52,10 @@ explicitly check the $lastexitcode variable. ### EXAMPLE 1 -Execute \{ svn info $repository_trunk \} "Error executing SVN. Please verify SVN command-line client is installed" +```powershell +Execute { svn info $repository_trunk } "Error executing SVN. Please verify SVN command-line client is installed" +``` + This example calls the svn command-line client. diff --git a/docs/commands/FormatTaskName.mdx b/docs/commands/FormatTaskName.mdx index 995e41f..9392a70 100644 --- a/docs/commands/FormatTaskName.mdx +++ b/docs/commands/FormatTaskName.mdx @@ -41,7 +41,10 @@ This function takes either a string which represents a format string (formats us ### EXAMPLE 1 +```powershell A sample build script that uses a format string is shown below: +``` + Task default -depends TaskA, TaskB, TaskC @@ -72,7 +75,10 @@ Build Succeeded! ### EXAMPLE 2 +```powershell A sample build script that uses a ScriptBlock is shown below: +``` + Task default -depends TaskA, TaskB, TaskC diff --git a/docs/commands/Framework.mdx b/docs/commands/Framework.mdx index b5fa96e..7692b8e 100644 --- a/docs/commands/Framework.mdx +++ b/docs/commands/Framework.mdx @@ -47,11 +47,14 @@ the PowerShell process. ### EXAMPLE 1 +```powershell Framework "4.0" Task default -depends Compile -Task Compile -depends Clean \{ +Task Compile -depends Clean { msbuild /version -\} +} +``` + The script above will output detailed version of msbuid v4 diff --git a/docs/commands/Get-PSakeScriptTasks.mdx b/docs/commands/Get-PSakeScriptTasks.mdx index 032f13b..35aef7e 100644 --- a/docs/commands/Get-PSakeScriptTasks.mdx +++ b/docs/commands/Get-PSakeScriptTasks.mdx @@ -41,7 +41,10 @@ Returns meta data about all the tasks defined in the provided psake script. ### EXAMPLE 1 +```powershell Get-PSakeScriptTasks -BuildFile '.\build.ps1' +``` + DependsOn Alias Name Description --------- ----- ---- ----------- diff --git a/docs/commands/Get-PsakeBuildPlan.mdx b/docs/commands/Get-PsakeBuildPlan.mdx index d14f014..5cf6236 100644 --- a/docs/commands/Get-PsakeBuildPlan.mdx +++ b/docs/commands/Get-PsakeBuildPlan.mdx @@ -58,25 +58,34 @@ resolve properties, setup, and teardown blocks. ### EXAMPLE 1 +```powershell $plan = Get-PsakeBuildPlan -BuildFile './psakefile.ps1' $plan.Tasks | Should -HaveCount 4 $plan.ExecutionOrder | Should -Be @('Clean', 'Compile', 'Test', 'Default') +``` + This example compiles the build file and asserts that there are 4 tasks and that the execution order is correct. ### EXAMPLE 2 +```powershell $plan = Get-PsakeBuildPlan $plan.TaskMap['build'].DependsOn | Should -Contain 'Clean' $plan.IsValid | Should -BeTrue +``` + This example compiles the default build file and asserts that the 'build' task depends on the 'Clean' task and that the plan is valid. ### EXAMPLE 3 +```powershell Get-PsakeBuildPlan -BuildFile './psakefile.ps1' | Invoke-Psake +``` + Compiles the build plan and pipes it into Invoke-Psake for execution. Note: the build file is re-loaded during the execution phase. diff --git a/docs/commands/Include.mdx b/docs/commands/Include.mdx index 494f5ae..00b6c82 100644 --- a/docs/commands/Include.mdx +++ b/docs/commands/Include.mdx @@ -52,14 +52,17 @@ after code from build script. ### EXAMPLE 1 +```powershell Include ".\build_utils.ps1" Task default -depends Test -Task Test -depends Compile, Clean \{ -\} -Task Compile -depends Clean \{ -\} -Task Clean \{ -\} +Task Test -depends Compile, Clean { +} +Task Compile -depends Clean { +} +Task Clean { +} +``` + The script above includes all the functions and variables defined in the ".\build_utils.ps1" script into the current build script's scope @@ -67,8 +70,11 @@ Note: You can have more than 1 "Include" function defined in the build script. ### EXAMPLE 2 +```powershell @("File1.ps1","File2.ps1") | Include Get-ChildItem | Include +``` + Strings or FileInfo objects can be piped to the Include function diff --git a/docs/commands/Invoke-Psake.mdx b/docs/commands/Invoke-Psake.mdx index 1b7080c..68c6e7f 100644 --- a/docs/commands/Invoke-Psake.mdx +++ b/docs/commands/Invoke-Psake.mdx @@ -51,25 +51,37 @@ execution phase to resolve properties, setup, and teardown blocks. ### EXAMPLE 1 +```powershell Invoke-psake +``` + Runs the 'default' task in the 'psakefile.ps1' build script ### EXAMPLE 2 +```powershell Invoke-psake '.\build.ps1' Tests,Package +``` + Runs the 'Tests' and 'Package' tasks in the 'build.ps1' build script ### EXAMPLE 3 +```powershell Invoke-psake -CompileOnly +``` + Returns the build plan without executing any tasks. ### EXAMPLE 4 +```powershell Get-PsakeBuildPlan | Invoke-Psake +``` + Compiles the build plan then executes it. The build file is re-loaded @@ -77,7 +89,10 @@ during the execution phase. ### EXAMPLE 5 +```powershell Invoke-psake -OutputFormat JSON +``` + Runs the build and outputs the result as JSON. diff --git a/docs/commands/Invoke-Task.mdx b/docs/commands/Invoke-Task.mdx index ae18786..8e8807e 100644 --- a/docs/commands/Invoke-Task.mdx +++ b/docs/commands/Invoke-Task.mdx @@ -42,7 +42,10 @@ Task in the current build script. ### EXAMPLE 1 +```powershell Invoke-Task "Compile" +``` + This example calls the "Compile" task. diff --git a/docs/commands/Properties.mdx b/docs/commands/Properties.mdx index 16a74cc..2d24b1d 100644 --- a/docs/commands/Properties.mdx +++ b/docs/commands/Properties.mdx @@ -50,29 +50,35 @@ the build script. ### EXAMPLE 1 -Properties \{ +```powershell +Properties { $build_dir = "c:\build" $connection_string = "datasource=localhost;initial catalog=northwind;integrated security=sspi" -\} +} Task default -depends Test -Task Test -depends Compile, Clean \{ -\} -Task Compile -depends Clean \{ -\} -Task Clean \{ -\} +Task Test -depends Compile, Clean { +} +Task Compile -depends Clean { +} +Task Clean { +} +``` + Note: You can have more than one "Properties" function defined in the build script. ### EXAMPLE 2 -Properties \{ +```powershell +Properties { $script:build_dir = "c:\build" $script:connection_string = "datasource=localhost;initial catalog=northwind;integrated security=sspi" -\} -Task Compile \{ +} +Task Compile { "Building to: $build_dir" # No PSScriptAnalyzer warning, variable is recognized -\} +} +``` + Recommended: Use script-scoped variables to avoid PSScriptAnalyzer warnings The $script: prefix has identical runtime behavior but satisfies @@ -80,12 +86,15 @@ PSScriptAnalyzer's static analysis requirements. ### EXAMPLE 3 -Properties \{ +```powershell +Properties { $build_dir = "c:\build" # Warning: PSUseDeclaredVarsMoreThanAssignments -\} -Task Compile \{ +} +Task Compile { "Building to: $build_dir" # Works at runtime, but PSScriptAnalyzer warns -\} +} +``` + Alternative: Non-scoped variables (generates PSScriptAnalyzer warnings) diff --git a/docs/commands/Task.mdx b/docs/commands/Task.mdx index 970a135..a4d4d7c 100644 --- a/docs/commands/Task.mdx +++ b/docs/commands/Task.mdx @@ -62,16 +62,19 @@ Note: There must be at least one task called 'default' in the build script ### EXAMPLE 1 +```powershell Task default -Depends Test -Task Test -Depends Compile, Clean \{ +Task Test -Depends Compile, Clean { "This is a test" -\} -Task Compile -Depends Clean \{ +} +Task Compile -Depends Clean { "Compile" -\} -Task Clean \{ +} +Task Clean { "Clean" -\} +} +``` + The 'default' task is required and should not contain an 'Action' parameter. It uses the 'Depends' parameter to specify that 'Test' is a dependency diff --git a/docs/commands/TaskSetup.mdx b/docs/commands/TaskSetup.mdx index 752d1e5..52241f3 100644 --- a/docs/commands/TaskSetup.mdx +++ b/docs/commands/TaskSetup.mdx @@ -43,16 +43,19 @@ The scriptblock accepts an optional parameter which describes the Task being set ### EXAMPLE 1 +```powershell Task default -Depends Test -Task Test -Depends Compile, Clean \{ -\} -Task Compile -Depends Clean \{ -\} -Task Clean \{ -\} -TaskSetup \{ +Task Test -Depends Compile, Clean { +} +Task Compile -Depends Clean { +} +Task Clean { +} +TaskSetup { "Running 'TaskSetup' for task $context.Peek().currentTaskName" -\} +} +``` + The script above produces the following output: @@ -67,15 +70,18 @@ Build Succeeded ### EXAMPLE 2 +```powershell Task default -Depends Test -Task Test -Depends Compile, Clean \{ -\} -Task Compile -Depends Clean \{ -\} -Task Clean \{ -\} -TaskSetup \{ +Task Test -Depends Compile, Clean { +} +Task Compile -Depends Clean { +} +Task Clean { +} +TaskSetup { param($task) +``` + "Running 'TaskSetup' for task $($task.Name)" \} diff --git a/docs/commands/TaskTearDown.mdx b/docs/commands/TaskTearDown.mdx index 32ddfe7..8eb4dbf 100644 --- a/docs/commands/TaskTearDown.mdx +++ b/docs/commands/TaskTearDown.mdx @@ -45,17 +45,20 @@ torn down. ### EXAMPLE 1 +```powershell Task default -Depends Test -Task Test -Depends Compile, Clean \{ -\} -Task Compile -Depends Clean \{ -\} -Task Clean \{ -\} -TaskTearDown \{ +Task Test -Depends Compile, Clean { +} +Task Compile -Depends Clean { +} +Task Clean { +} +TaskTearDown { "Running 'TaskTearDown' for task $context.Peek().currentTaskName" -\} +} The script above produces the following output: +``` + Executing task, Clean... Running 'TaskTearDown' for task Clean @@ -68,15 +71,18 @@ Build Succeeded ### EXAMPLE 2 +```powershell Task default -Depends Test -Task Test -Depends Compile, Clean \{ -\} -Task Compile -Depends Clean \{ -\} -Task Clean \{ -\} -TaskTearDown \{ +Task Test -Depends Compile, Clean { +} +Task Compile -Depends Clean { +} +Task Clean { +} +TaskTearDown { param($task) +``` + if ($task.Success) \{ "Running 'TaskTearDown' for task $($task.Name) - success!" diff --git a/docs/commands/Test-BuildEnvironment.mdx b/docs/commands/Test-BuildEnvironment.mdx index 0df2b49..582c84e 100644 --- a/docs/commands/Test-BuildEnvironment.mdx +++ b/docs/commands/Test-BuildEnvironment.mdx @@ -83,23 +83,32 @@ rest of test ### EXAMPLE 1 +```powershell Test-BuildEnvironment -Framework '4.8' +``` + Returns $true when MSBuild 17.0 or 16.0 and the v4.0.30319 runtime directory are both present. ### EXAMPLE 2 +```powershell Test-BuildEnvironment -BuildFile './psakefile.ps1' +``` + Loads the build file, reads its Framework setting, and returns $true if that framework is installed. ### EXAMPLE 3 -if (-not (Test-BuildEnvironment)) \{ +```powershell +if (-not (Test-BuildEnvironment)) { Write-Warning "Build environment not ready for current framework" -\} +} +``` + Tests the framework configured in the active psake context. diff --git a/docs/commands/Test-PsakeTask.mdx b/docs/commands/Test-PsakeTask.mdx index c8df2c5..e909b54 100644 --- a/docs/commands/Test-PsakeTask.mdx +++ b/docs/commands/Test-PsakeTask.mdx @@ -49,11 +49,14 @@ executed.This enables unit-testing individual tasks. ### EXAMPLE 1 -$result = Test-PsakeTask -BuildFile './psakefile.ps1' -TaskName 'Build' -Variables @\{ +```powershell +$result = Test-PsakeTask -BuildFile './psakefile.ps1' -TaskName 'Build' -Variables @{ Configuration = 'Debug' OutputDir = './test-output' -\} +} $result.Success | Should -BeTrue +``` + This example runs the 'Build' task from 'psakefile.ps1' with two variables injected into the task's scope. diff --git a/docs/commands/Version.mdx b/docs/commands/Version.mdx index f5667ea..5598e78 100644 --- a/docs/commands/Version.mdx +++ b/docs/commands/Version.mdx @@ -48,7 +48,10 @@ that the running psake version matches. ### EXAMPLE 1 +```powershell Version 5 +``` + Declares that this build script requires psake v5. diff --git a/scripts/New-DocusaurusModuleHelp.ps1 b/scripts/New-DocusaurusModuleHelp.ps1 index 10469ba..e24f817 100644 --- a/scripts/New-DocusaurusModuleHelp.ps1 +++ b/scripts/New-DocusaurusModuleHelp.ps1 @@ -113,6 +113,20 @@ function ConvertTo-DocusaurusMdx { # Convert markdown parameter tables to yaml fenced blocks $body = Convert-ParameterTablesToYamlFences -Body $body + # Wrap example code in powershell fenced blocks. + # PlatyPS v2 outputs example code as plain text; detect the first paragraph of each + # ### EXAMPLE section (before the first blank line) and wrap it. Skip if already fenced. + $body = [System.Text.RegularExpressions.Regex]::Replace( + $body, + '(?m)^(### EXAMPLE [^\r\n]+)\r?\n\r?\n(?!```)([^\r\n][^\r\n]*(?:\r?\n(?!\r?\n)[^\r\n][^\r\n]*)*)', + { + param($m) + $header = $m.Groups[1].Value + $code = $m.Groups[2].Value.TrimEnd() + "$header`n`n``````powershell`n$code`n```````n" + } + ) + # Fix RELATED LINKS: [Name]() -> [Name](/docs//Name) for known commands, strip unknown foreach ($cmd in $AllCommandNames) { $escaped = [regex]::Escape($cmd) From 7c20728fc6b86b6cf4ac093573720f3f08e607ad Mon Sep 17 00:00:00 2001 From: Gilbert Sanchez Date: Tue, 28 Apr 2026 13:02:17 -0700 Subject: [PATCH 09/11] Strip PlatyPS placeholder content; warn on unfilled CBH fields MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove ## ALIASES section when it contains only the no-aliases placeholder (PlatyPS v2 emits this for every command with no real aliases) - Remove '{{ Fill in the related links here }}' from RELATED LINKS sections - Warn via Write-Warning for any remaining {{...}} placeholders after cleanup (currently: Include, Invoke-Psake, Test-BuildEnvironment have unfilled Description fields in their CBH — these should be fixed upstream in psake) Co-Authored-By: Claude Sonnet 4.6 --- docs/commands/Assert.mdx | 7 ------- docs/commands/BuildSetup.mdx | 7 ------- docs/commands/BuildTearDown.mdx | 7 ------- docs/commands/Clear-PsakeCache.mdx | 5 ----- docs/commands/Execute.mdx | 7 ------- docs/commands/FormatTaskName.mdx | 7 ------- docs/commands/Framework.mdx | 7 ------- docs/commands/Get-PSakeScriptTasks.mdx | 7 ------- docs/commands/Get-PsakeBuildPlan.mdx | 7 ------- docs/commands/Include.mdx | 7 ------- docs/commands/Invoke-Psake.mdx | 7 ------- docs/commands/Invoke-Task.mdx | 7 ------- docs/commands/Properties.mdx | 7 ------- docs/commands/Task.mdx | 7 ------- docs/commands/TaskSetup.mdx | 7 ------- docs/commands/TaskTearDown.mdx | 7 ------- docs/commands/Test-BuildEnvironment.mdx | 7 ------- docs/commands/Test-PsakeTask.mdx | 7 ------- docs/commands/Version.mdx | 7 ------- scripts/New-DocusaurusModuleHelp.ps1 | 13 +++++++++++++ 20 files changed, 13 insertions(+), 131 deletions(-) diff --git a/docs/commands/Assert.mdx b/docs/commands/Assert.mdx index eeecf70..445148e 100644 --- a/docs/commands/Assert.mdx +++ b/docs/commands/Assert.mdx @@ -28,11 +28,6 @@ Helper function for "Design by Contract" assertion checking. Assert [-ConditionToCheck] [-FailureMessage] [] ``` -## ALIASES - -This cmdlet has the following aliases, - \{\{Insert list of aliases\}\} - ## DESCRIPTION This is a helper function that makes the code less noisy by eliminating many of the "if" statements that are normally required to verify assumptions in the code. @@ -130,7 +125,5 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -\{\{ Fill in the related links here \}\} - ## VERSION *This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/BuildSetup.mdx b/docs/commands/BuildSetup.mdx index ac5a8a5..958dba7 100644 --- a/docs/commands/BuildSetup.mdx +++ b/docs/commands/BuildSetup.mdx @@ -32,11 +32,6 @@ Adds a scriptblock that will be executed once at the beginning of the build BuildSetup [-Setup] [] ``` -## ALIASES - -This cmdlet has the following aliases, - \{\{Insert list of aliases\}\} - ## DESCRIPTION This function will accept a scriptblock that will be executed once at the @@ -105,7 +100,5 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -\{\{ Fill in the related links here \}\} - ## VERSION *This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/BuildTearDown.mdx b/docs/commands/BuildTearDown.mdx index daa968b..63bdef8 100644 --- a/docs/commands/BuildTearDown.mdx +++ b/docs/commands/BuildTearDown.mdx @@ -32,11 +32,6 @@ Adds a scriptblock that will be executed once at the end of the build BuildTearDown [-Setup] [] ``` -## ALIASES - -This cmdlet has the following aliases, - \{\{Insert list of aliases\}\} - ## DESCRIPTION This function will accept a scriptblock that will be executed once at the @@ -130,7 +125,5 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -\{\{ Fill in the related links here \}\} - ## VERSION *This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Clear-PsakeCache.mdx b/docs/commands/Clear-PsakeCache.mdx index 218b210..29f4a4d 100644 --- a/docs/commands/Clear-PsakeCache.mdx +++ b/docs/commands/Clear-PsakeCache.mdx @@ -32,11 +32,6 @@ Clears the psake build cache. Clear-PsakeCache [[-Path] ] [[-TaskName] ] [] ``` -## ALIASES - -This cmdlet has the following aliases, - \{\{Insert list of aliases\}\} - ## DESCRIPTION Removes cached task state from the .psake/cache/ directory. diff --git a/docs/commands/Execute.mdx b/docs/commands/Execute.mdx index 20e93cd..0cdca46 100644 --- a/docs/commands/Execute.mdx +++ b/docs/commands/Execute.mdx @@ -34,11 +34,6 @@ Execute [-Cmd] [[-ErrorMessage] ] [[-MaxRetries] ] [-NewProcess] [] ``` -## ALIASES - -This cmdlet has the following aliases, - \{\{Insert list of aliases\}\} - ## DESCRIPTION This is a helper function that runs a scriptblock and checks the PS variable @@ -234,7 +229,5 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -\{\{ Fill in the related links here \}\} - ## VERSION *This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/FormatTaskName.mdx b/docs/commands/FormatTaskName.mdx index 9392a70..e50c43d 100644 --- a/docs/commands/FormatTaskName.mdx +++ b/docs/commands/FormatTaskName.mdx @@ -28,11 +28,6 @@ This function allows you to change how psake renders the task name during a buil FormatTaskName [-Format] [] ``` -## ALIASES - -This cmdlet has the following aliases, - \{\{Insert list of aliases\}\} - ## DESCRIPTION This function takes either a string which represents a format string (formats using the -f format operator see "help about_operators") or it can accept a script block that has a single parameter that is the name of the task that will be executed. @@ -142,7 +137,5 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -\{\{ Fill in the related links here \}\} - ## VERSION *This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Framework.mdx b/docs/commands/Framework.mdx index 7692b8e..9f5ad3d 100644 --- a/docs/commands/Framework.mdx +++ b/docs/commands/Framework.mdx @@ -28,11 +28,6 @@ Sets the version of the .NET framework you want to use during build. Framework [-Framework] [] ``` -## ALIASES - -This cmdlet has the following aliases, - \{\{Insert list of aliases\}\} - ## DESCRIPTION This function will accept a string containing version of the .NET framework @@ -96,7 +91,5 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -\{\{ Fill in the related links here \}\} - ## VERSION *This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Get-PSakeScriptTasks.mdx b/docs/commands/Get-PSakeScriptTasks.mdx index 35aef7e..5a854f8 100644 --- a/docs/commands/Get-PSakeScriptTasks.mdx +++ b/docs/commands/Get-PSakeScriptTasks.mdx @@ -28,11 +28,6 @@ Returns meta data about all the tasks defined in the provided psake script. Get-PSakeScriptTasks [[-BuildFile] ] [] ``` -## ALIASES - -This cmdlet has the following aliases, - \{\{Insert list of aliases\}\} - ## DESCRIPTION Returns meta data about all the tasks defined in the provided psake script. @@ -93,7 +88,5 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -\{\{ Fill in the related links here \}\} - ## VERSION *This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Get-PsakeBuildPlan.mdx b/docs/commands/Get-PsakeBuildPlan.mdx index 5cf6236..3fa2102 100644 --- a/docs/commands/Get-PsakeBuildPlan.mdx +++ b/docs/commands/Get-PsakeBuildPlan.mdx @@ -32,11 +32,6 @@ Compiles a build file and returns the build plan without executing any tasks. Get-PsakeBuildPlan [[-BuildFile] ] [[-TaskList] ] [] ``` -## ALIASES - -This cmdlet has the following aliases, - \{\{Insert list of aliases\}\} - ## DESCRIPTION This is the primary testability API for psake v5. @@ -151,7 +146,5 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -\{\{ Fill in the related links here \}\} - ## VERSION *This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Include.mdx b/docs/commands/Include.mdx index 00b6c82..9e429a1 100644 --- a/docs/commands/Include.mdx +++ b/docs/commands/Include.mdx @@ -35,11 +35,6 @@ Include [-Path] [] Include [-LiteralPath] [] ``` -## ALIASES - -This cmdlet has the following aliases, - \{\{Insert list of aliases\}\} - ## DESCRIPTION A build script may declare an "includes" function which allows you to define @@ -144,7 +139,5 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -\{\{ Fill in the related links here \}\} - ## VERSION *This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Invoke-Psake.mdx b/docs/commands/Invoke-Psake.mdx index 68c6e7f..ed21aa4 100644 --- a/docs/commands/Invoke-Psake.mdx +++ b/docs/commands/Invoke-Psake.mdx @@ -31,11 +31,6 @@ Invoke-Psake [[-BuildFile] ] [[-TaskList] ] [[-Framework] ] [] ``` -## ALIASES - -This cmdlet has the following aliases, - \{\{Insert list of aliases\}\} - ## DESCRIPTION This function runs a psake build script using a two-phase compile/run model. @@ -460,7 +455,5 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -\{\{ Fill in the related links here \}\} - ## VERSION *This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Invoke-Task.mdx b/docs/commands/Invoke-Task.mdx index 8e8807e..0eba097 100644 --- a/docs/commands/Invoke-Task.mdx +++ b/docs/commands/Invoke-Task.mdx @@ -28,11 +28,6 @@ Executes another task in the current build script. Invoke-Task [-TaskName] [] ``` -## ALIASES - -This cmdlet has the following aliases, - \{\{Insert list of aliases\}\} - ## DESCRIPTION This is a function that will allow you to invoke a Task from within another @@ -87,7 +82,5 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -\{\{ Fill in the related links here \}\} - ## VERSION *This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Properties.mdx b/docs/commands/Properties.mdx index 2d24b1d..e49dcb5 100644 --- a/docs/commands/Properties.mdx +++ b/docs/commands/Properties.mdx @@ -35,11 +35,6 @@ Properties [-Properties] [] Properties [-Hashtable] [] ``` -## ALIASES - -This cmdlet has the following aliases, - \{\{Insert list of aliases\}\} - ## DESCRIPTION A build script may declare a "Properties" function which allows you to @@ -189,7 +184,5 @@ See the examples above for more details. ## RELATED LINKS -\{\{ Fill in the related links here \}\} - ## VERSION *This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Task.mdx b/docs/commands/Task.mdx index a4d4d7c..16bbefc 100644 --- a/docs/commands/Task.mdx +++ b/docs/commands/Task.mdx @@ -47,11 +47,6 @@ Task [-Name] [[-Action] ] -FromModule [-PreAction Task [-Name] [[-Definition] ] [] ``` -## ALIASES - -This cmdlet has the following aliases, - \{\{Insert list of aliases\}\} - ## DESCRIPTION This function creates a 'task' object that will be used by the psake engine @@ -574,7 +569,5 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -\{\{ Fill in the related links here \}\} - ## VERSION *This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/TaskSetup.mdx b/docs/commands/TaskSetup.mdx index 52241f3..c5c2670 100644 --- a/docs/commands/TaskSetup.mdx +++ b/docs/commands/TaskSetup.mdx @@ -28,11 +28,6 @@ Adds a scriptblock that will be executed before each task TaskSetup [-Setup] [] ``` -## ALIASES - -This cmdlet has the following aliases, - \{\{Insert list of aliases\}\} - ## DESCRIPTION This function will accept a scriptblock that will be executed before each task in the build script. @@ -135,7 +130,5 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -\{\{ Fill in the related links here \}\} - ## VERSION *This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/TaskTearDown.mdx b/docs/commands/TaskTearDown.mdx index 8eb4dbf..cdf506a 100644 --- a/docs/commands/TaskTearDown.mdx +++ b/docs/commands/TaskTearDown.mdx @@ -28,11 +28,6 @@ Adds a scriptblock to the build that will be executed after each task TaskTearDown [-TearDown] [] ``` -## ALIASES - -This cmdlet has the following aliases, - \{\{Insert list of aliases\}\} - ## DESCRIPTION This function will accept a scriptblock that will be executed after each @@ -140,7 +135,5 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -\{\{ Fill in the related links here \}\} - ## VERSION *This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Test-BuildEnvironment.mdx b/docs/commands/Test-BuildEnvironment.mdx index 582c84e..d665e15 100644 --- a/docs/commands/Test-BuildEnvironment.mdx +++ b/docs/commands/Test-BuildEnvironment.mdx @@ -39,11 +39,6 @@ Test-BuildEnvironment [[-Framework] ] [] Test-BuildEnvironment -BuildFile [] ``` -## ALIASES - -This cmdlet has the following aliases, - \{\{Insert list of aliases\}\} - ## DESCRIPTION Resolves the MSBuild and .NET runtime directories for the specified @@ -184,7 +179,5 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -\{\{ Fill in the related links here \}\} - ## VERSION *This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Test-PsakeTask.mdx b/docs/commands/Test-PsakeTask.mdx index e909b54..bc6ccc9 100644 --- a/docs/commands/Test-PsakeTask.mdx +++ b/docs/commands/Test-PsakeTask.mdx @@ -33,11 +33,6 @@ Test-PsakeTask [[-BuildFile] ] [-TaskName] [[-Variables] ] ``` -## ALIASES - -This cmdlet has the following aliases, - \{\{Insert list of aliases\}\} - ## DESCRIPTION Compiles the build file, finds the specified task, and executes only its @@ -150,7 +145,5 @@ Action scriptblock in isolation. ## RELATED LINKS -\{\{ Fill in the related links here \}\} - ## VERSION *This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/docs/commands/Version.mdx b/docs/commands/Version.mdx index 5598e78..09bd17f 100644 --- a/docs/commands/Version.mdx +++ b/docs/commands/Version.mdx @@ -32,11 +32,6 @@ Declares the required psake version for the build script. Version [-RequiredVersion] [] ``` -## ALIASES - -This cmdlet has the following aliases, - \{\{Insert list of aliases\}\} - ## DESCRIPTION Use this function at the top of a psake build script to declare which @@ -94,7 +89,5 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -\{\{ Fill in the related links here \}\} - ## VERSION *This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* diff --git a/scripts/New-DocusaurusModuleHelp.ps1 b/scripts/New-DocusaurusModuleHelp.ps1 index e24f817..88d96e6 100644 --- a/scripts/New-DocusaurusModuleHelp.ps1 +++ b/scripts/New-DocusaurusModuleHelp.ps1 @@ -134,6 +134,19 @@ function ConvertTo-DocusaurusMdx { } $body = $body -replace '\[([^\]]+)\]\(\)', '$1' + # Strip PlatyPS placeholder sections before MDX escaping. + # Remove ## ALIASES section when it contains only the "no aliases" placeholder. + $body = $body -replace '(?ms)^## ALIASES\r?\n\r?\nThis cmdlet has the following aliases,\r?\n \{\{Insert list of aliases\}\}\r?\n(\r?\n)?', '' + # Remove the "Fill in the related links here" placeholder (keep real links if any). + $body = $body -replace '\{\{ Fill in the related links here \}\}\r?\n', '' + + # Warn about any remaining {{...}} placeholders — these indicate unfilled CBH fields. + $remainingPlaceholders = [regex]::Matches($body, '\{\{[^}]+\}\}') + if ($remainingPlaceholders.Count -gt 0) { + $unique = $remainingPlaceholders | ForEach-Object { $_.Value } | Sort-Object -Unique + Write-Warning "$CommandName`: unfilled placeholder(s): $($unique -join ', ')" + } + # Escape curly braces outside code fences (required for MDX/JSX compatibility) $body = Escape-CurlyBracesOutsideCodeFences -Body $body From 83fe6023f265ffd80b417af8f4f0c34ab06f4e78 Mon Sep 17 00:00:00 2001 From: Gilbert Sanchez Date: Thu, 30 Apr 2026 09:46:17 -0700 Subject: [PATCH 10/11] Fix CI: remove -Import flag from Invoke-PSDepend to prevent Pester assembly conflict The GitHub runner has Pester 5.7.1 pre-installed and already loaded. Passing -Import to Invoke-PSDepend overrides the per-dependency `Import = $false` set for Pester in requirements.psd1, causing PSDepend to re-import an already-loaded assembly ("Assembly with same name is already loaded"). Removing -Import lets modules install to CurrentUser scope (standard PSModulePath) and auto-import on first use, which is how they work in practice anyway. Co-Authored-By: Claude Sonnet 4.6 --- build.ps1 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/build.ps1 b/build.ps1 index 5797458..5cb4757 100644 --- a/build.ps1 +++ b/build.ps1 @@ -50,7 +50,7 @@ if ($Bootstrap) { Install-Module -Name PSDepend -Repository PSGallery -Scope CurrentUser -Force } Import-Module -Name PSDepend -Verbose:$false - Invoke-PSDepend -Path './requirements.psd1' -Install -Import -Force -WarningAction SilentlyContinue + Invoke-PSDepend -Path './requirements.psd1' -Install -Force -WarningAction SilentlyContinue } else { Write-Warning 'No [requirements.psd1] found. Skipping build dependency installation.' } From 34b455629f7662df3754441e6ade3a9f53e9ac2c Mon Sep 17 00:00:00 2001 From: Gilbert Sanchez Date: Thu, 30 Apr 2026 13:12:54 -0700 Subject: [PATCH 11/11] Regenerate command docs from psake 5.0.4; strip INPUTS placeholders Updates all 19 command MDX files using improved CBH from psake 5.0.4. Also strips PlatyPS-generated {{ Fill in the Description }} placeholders from INPUTS sections so they no longer appear in rendered docs or trigger generator warnings. Co-Authored-By: Claude Sonnet 4.6 --- docs/commands/Assert.mdx | 35 +++++++---- docs/commands/BuildSetup.mdx | 21 ++++--- docs/commands/BuildTearDown.mdx | 30 ++++----- docs/commands/Clear-PsakeCache.mdx | 2 +- docs/commands/Execute.mdx | 10 +-- docs/commands/FormatTaskName.mdx | 84 ++++++++++++------------- docs/commands/Framework.mdx | 21 ++++--- docs/commands/Get-PSakeScriptTasks.mdx | 6 +- docs/commands/Get-PsakeBuildPlan.mdx | 2 +- docs/commands/Include.mdx | 29 ++++----- docs/commands/Invoke-Psake.mdx | 19 +++--- docs/commands/Invoke-Task.mdx | 6 +- docs/commands/Properties.mdx | 31 +++------ docs/commands/Task.mdx | 65 ++++--------------- docs/commands/TaskSetup.mdx | 29 ++++----- docs/commands/TaskTearDown.mdx | 39 ++++++------ docs/commands/Test-BuildEnvironment.mdx | 9 +-- docs/commands/Test-PsakeTask.mdx | 8 +-- docs/commands/Version.mdx | 2 +- scripts/New-DocusaurusModuleHelp.ps1 | 3 + 20 files changed, 205 insertions(+), 246 deletions(-) diff --git a/docs/commands/Assert.mdx b/docs/commands/Assert.mdx index 445148e..e5accac 100644 --- a/docs/commands/Assert.mdx +++ b/docs/commands/Assert.mdx @@ -30,7 +30,9 @@ Assert [-ConditionToCheck] [-FailureMessage] [ [] ## DESCRIPTION -This function will accept a scriptblock that will be executed once at the -beginning of the build. +Runs once before the first task executes. +Use this to set up shared +state, logging, or environment validation for the whole build. ## EXAMPLES @@ -43,12 +44,9 @@ beginning of the build. ```powershell Task default -Depends Test -Task Test -Depends Compile, Clean { -} -Task Compile -Depends Clean { -} -Task Clean { -} +Task Test -Depends Compile, Clean {} +Task Compile -Depends Clean {} +Task Clean {} BuildSetup { "Running 'BuildSetup'" } @@ -56,17 +54,20 @@ BuildSetup { The script above produces the following output: + +``` Running 'BuildSetup' Executing task, Clean... Executing task, Compile... Executing task, Test... Build Succeeded +``` ## PARAMETERS ### -Setup -A scriptblock to execute +Executed once before any tasks run. ```yaml Type: System.Management.Automation.ScriptBlock @@ -101,4 +102,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS ## VERSION -*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.4](https://github.com/psake/psake).* diff --git a/docs/commands/BuildTearDown.mdx b/docs/commands/BuildTearDown.mdx index 63bdef8..1f52490 100644 --- a/docs/commands/BuildTearDown.mdx +++ b/docs/commands/BuildTearDown.mdx @@ -34,8 +34,9 @@ BuildTearDown [-Setup] [] ## DESCRIPTION -This function will accept a scriptblock that will be executed once at the -end of the build, regardless of success or failure +Runs after all tasks complete, even if the build failed. +Use this for +cleanup, notifications, or post-build reporting. ## EXAMPLES @@ -43,12 +44,9 @@ end of the build, regardless of success or failure ```powershell Task default -Depends Test -Task Test -Depends Compile, Clean { -} -Task Compile -Depends Clean { -} -Task Clean { -} +Task Test -Depends Compile, Clean {} +Task Compile -Depends Clean {} +Task Clean {} BuildTearDown { "Running 'BuildTearDown'" } @@ -56,11 +54,14 @@ BuildTearDown { The script above produces the following output: + +``` Executing task, Clean... Executing task, Compile... Executing task, Test... Running 'BuildTearDown' Build Succeeded +``` ### EXAMPLE 2 @@ -69,10 +70,8 @@ Task default -Depends Test Task Test -Depends Compile, Clean { throw "forced error" } -Task Compile -Depends Clean { -} -Task Clean { -} +Task Compile -Depends Clean {} +Task Clean {} BuildTearDown { "Running 'BuildTearDown'" } @@ -80,18 +79,21 @@ BuildTearDown { The script above produces the following output: + +``` Executing task, Clean... Executing task, Compile... Executing task, Test... Running 'BuildTearDown' forced error At line:x char:x ... +``` ## PARAMETERS ### -Setup -A scriptblock to execute +Executed after all tasks finish, whether or not the build succeeded. ```yaml Type: System.Management.Automation.ScriptBlock @@ -126,4 +128,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS ## VERSION -*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.4](https://github.com/psake/psake).* diff --git a/docs/commands/Clear-PsakeCache.mdx b/docs/commands/Clear-PsakeCache.mdx index 29f4a4d..ec3dcfa 100644 --- a/docs/commands/Clear-PsakeCache.mdx +++ b/docs/commands/Clear-PsakeCache.mdx @@ -121,4 +121,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable - [Invoke-Psake](/docs/commands/Invoke-Psake) ## VERSION -*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.4](https://github.com/psake/psake).* diff --git a/docs/commands/Execute.mdx b/docs/commands/Execute.mdx index 0cdca46..9e4933d 100644 --- a/docs/commands/Execute.mdx +++ b/docs/commands/Execute.mdx @@ -36,12 +36,8 @@ Execute [-Cmd] [[-ErrorMessage] ] [[-MaxRetries] ] ## DESCRIPTION -This is a helper function that runs a scriptblock and checks the PS variable -$lastexitcode to see if an error occured. - -If an error is detected then an exception is thrown. -This function allows you to run command-line programs without having to -explicitly check the $lastexitcode variable. +Throws a terminating error if $lastexitcode is non-zero after the +command runs, so callers don't need to check it after each invocation. ## EXAMPLES @@ -230,4 +226,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS ## VERSION -*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.4](https://github.com/psake/psake).* diff --git a/docs/commands/FormatTaskName.mdx b/docs/commands/FormatTaskName.mdx index e50c43d..19779fb 100644 --- a/docs/commands/FormatTaskName.mdx +++ b/docs/commands/FormatTaskName.mdx @@ -18,7 +18,8 @@ Contributions are welcome in [Psake-repo](https://github.com/psake/psake). ## SYNOPSIS -This function allows you to change how psake renders the task name during a build. +This function allows you to change how psake renders the task name during a +build. ## SYNTAX @@ -30,35 +31,35 @@ FormatTaskName [-Format] [] ## DESCRIPTION -This function takes either a string which represents a format string (formats using the -f format operator see "help about_operators") or it can accept a script block that has a single parameter that is the name of the task that will be executed. +Useful for adding visual separators or color to task names in the +build output. +Accepts a -f format string or a scriptblock that +receives the task name as its only argument. ## EXAMPLES ### EXAMPLE 1 ```powershell -A sample build script that uses a format string is shown below: -``` - - Task default -depends TaskA, TaskB, TaskC +FormatTaskName "-------- {0} --------" +Task TaskA { + "TaskA is executing" +} +Task TaskB { + "TaskB is executing" +} +Task TaskC { + "TaskC is executing" +} +``` -FormatTaskName "-------- \{0\} --------" - -Task TaskA \{ -"TaskA is executing" -\} - -Task TaskB \{ -"TaskB is executing" -\} - -Task TaskC \{ -"TaskC is executing" ------------ -The script above produces the following output: +A sample build script that uses a format string. +The script above produces +the following output: +``` -------- TaskA -------- TaskA is executing -------- TaskB -------- @@ -67,37 +68,34 @@ TaskB is executing TaskC is executing Build Succeeded! +``` ### EXAMPLE 2 ```powershell -A sample build script that uses a ScriptBlock is shown below: -``` - - Task default -depends TaskA, TaskB, TaskC - -FormatTaskName \{ +FormatTaskName { param($taskName) - write-host "Executing Task: $taskName" -foregroundcolor blue -\} - -Task TaskA \{ -"TaskA is executing" -\} - -Task TaskB \{ -"TaskB is executing" -\} + write-host "Executing Task: $taskName" -ForegroundColor blue +} +Task TaskA { + "TaskA is executing" +} +Task TaskB { + "TaskB is executing" +} +Task TaskC { + "TaskC is executing" +} +``` -Task TaskC \{ -"TaskC is executing" -\} ------------ -The above example uses the scriptblock parameter to the FormatTaskName function to render each task name in the color blue. +A sample build script that uses a ScriptBlock. +The above example uses the +scriptblock parameter to the FormatTaskName function to render each task +name in the color blue. -Note: the $taskName parameter is arbitrary, it could be named anything. +Note: the $taskName parameter name is arbitrary, it could be named anything. ## PARAMETERS @@ -138,4 +136,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS ## VERSION -*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.4](https://github.com/psake/psake).* diff --git a/docs/commands/Framework.mdx b/docs/commands/Framework.mdx index 9f5ad3d..ddda1d2 100644 --- a/docs/commands/Framework.mdx +++ b/docs/commands/Framework.mdx @@ -30,13 +30,8 @@ Framework [-Framework] [] ## DESCRIPTION -This function will accept a string containing version of the .NET framework -to use during build. -Possible values: '1.0', '1.1', '2.0', '2.0x86', '2.0x64', '3.0', '3.0x86', -'3.0x64', '3.5', '3.5x86', '3.5x64', '4.0', '4.0x86', '4.0x64', '4.5', -'4.5x86', '4.5x64', '4.5.1', '4.5.1x86', '4.5.1x64'. -Default is '3.5*', where x86 or x64 will be detected based on the bitness of -the PowerShell process. +Overrides the psake default framework, determining which MSBuild and +runtime directories are used by all tasks in the build. ## EXAMPLES @@ -51,13 +46,19 @@ Task Compile -depends Clean { ``` -The script above will output detailed version of msbuid v4 +Uses MSBuild v4.0 for the build. ## PARAMETERS ### -Framework -Version of the .NET framework to use during build. +Framework version string. +Append 'x86' or 'x64' to force bitness; +otherwise bitness matches the current PowerShell process. +Supported values: '1.0', '1.1', '2.0', '2.0x86', '2.0x64', '3.0', +'3.0x86', '3.0x64', '3.5', '3.5x86', '3.5x64', '4.0', '4.0x86', +'4.0x64', '4.5', '4.5x86', '4.5x64', '4.5.1', '4.5.1x86', '4.5.1x64'. +Default is '3.5*' (bitness auto-detected). ```yaml Type: System.String @@ -92,4 +93,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS ## VERSION -*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.4](https://github.com/psake/psake).* diff --git a/docs/commands/Get-PSakeScriptTasks.mdx b/docs/commands/Get-PSakeScriptTasks.mdx index 5a854f8..5584c83 100644 --- a/docs/commands/Get-PSakeScriptTasks.mdx +++ b/docs/commands/Get-PSakeScriptTasks.mdx @@ -30,7 +30,9 @@ Get-PSakeScriptTasks [[-BuildFile] ] [] ## DESCRIPTION -Returns meta data about all the tasks defined in the provided psake script. +Loads the build file and evaluates task definitions without executing +any tasks. +Useful for tooling, IDE integrations, and tab completion. ## EXAMPLES @@ -89,4 +91,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS ## VERSION -*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.4](https://github.com/psake/psake).* diff --git a/docs/commands/Get-PsakeBuildPlan.mdx b/docs/commands/Get-PsakeBuildPlan.mdx index 3fa2102..12bf406 100644 --- a/docs/commands/Get-PsakeBuildPlan.mdx +++ b/docs/commands/Get-PsakeBuildPlan.mdx @@ -147,4 +147,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS ## VERSION -*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.4](https://github.com/psake/psake).* diff --git a/docs/commands/Include.mdx b/docs/commands/Include.mdx index 9e429a1..8623016 100644 --- a/docs/commands/Include.mdx +++ b/docs/commands/Include.mdx @@ -37,11 +37,9 @@ Include [-LiteralPath] [] ## DESCRIPTION -A build script may declare an "includes" function which allows you to define -a file containing powershell code to be included and added to the scope of -the currently running build script. -Code from such file will be executed -after code from build script. +Included scripts are dot-sourced into the build script's scope after +the build file finishes loading. +You can call Include more than once. ## EXAMPLES @@ -59,9 +57,8 @@ Task Clean { ``` -The script above includes all the functions and variables defined in the ".\build_utils.ps1" script into the current build script's scope - -Note: You can have more than 1 "Include" function defined in the build script. +Includes all functions and variables from build_utils.ps1 in the +build script's scope. ### EXAMPLE 2 @@ -77,8 +74,8 @@ Strings or FileInfo objects can be piped to the Include function ### -LiteralPath -A string containing the path and name of the powershell file to include (no -wildcards) +Path to the script file to include. +No wildcard expansion. ```yaml Type: System.String @@ -99,8 +96,8 @@ HelpMessage: '' ### -Path -A string containing the path and name of the powershell file to include -(wildcards can be used) +Path to the script file(s) to include. +Supports wildcards. ```yaml Type: System.String @@ -131,7 +128,11 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### System.String -\{\{ Fill in the Description \}\} +The path(s) to the script file(s) to include in the build. + + +### System.String + ## OUTPUTS @@ -140,4 +141,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS ## VERSION -*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.4](https://github.com/psake/psake).* diff --git a/docs/commands/Invoke-Psake.mdx b/docs/commands/Invoke-Psake.mdx index ed21aa4..8ee7b2c 100644 --- a/docs/commands/Invoke-Psake.mdx +++ b/docs/commands/Invoke-Psake.mdx @@ -322,11 +322,12 @@ HelpMessage: '' ### -OutputFormat -The output format. -'Default' for console output, 'JSON' for JSON to stdout, -'GitHubActions' for GitHub Actions workflow annotations (::error::, ::warning::, ::debug::), -'Annotated' for colored console output plus annotation lines for errors/warnings (VS Code problem matcher). -If not specified, the PSAKE_OUTPUT_FORMAT environment variable is checked as a fallback. +Output format. +'Default' for console, 'JSON' for stdout JSON, +'GitHubActions' for workflow annotations (::error::, ::warning::, +::debug::), 'Annotated' for console + annotation lines (VS Code +problem matcher). +Falls back to PSAKE_OUTPUT_FORMAT env variable. ```yaml Type: System.String @@ -447,7 +448,11 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### PsakeBuildPlan -\{\{ Fill in the Description \}\} +A pre-compiled build plan from Get-PsakeBuildPlan + + +### PsakeBuildPlan + ## OUTPUTS @@ -456,4 +461,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS ## VERSION -*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.4](https://github.com/psake/psake).* diff --git a/docs/commands/Invoke-Task.mdx b/docs/commands/Invoke-Task.mdx index 0eba097..a4ce37f 100644 --- a/docs/commands/Invoke-Task.mdx +++ b/docs/commands/Invoke-Task.mdx @@ -30,8 +30,8 @@ Invoke-Task [-TaskName] [] ## DESCRIPTION -This is a function that will allow you to invoke a Task from within another -Task in the current build script. +Use this inside a task's Action when you need to sequence tasks +programmatically rather than declaring them with -Depends. ## EXAMPLES @@ -83,4 +83,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS ## VERSION -*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.4](https://github.com/psake/psake).* diff --git a/docs/commands/Properties.mdx b/docs/commands/Properties.mdx index e49dcb5..72e1833 100644 --- a/docs/commands/Properties.mdx +++ b/docs/commands/Properties.mdx @@ -156,33 +156,16 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## NOTES -This works by defining a script block that is pushed onto the -$psake.Context.Peek().properties stack. -This allows the properties to be -accessed within all tasks in the build script. -This means that the variables defined in the script block will be -available in the scope of the tasks, but not in the global scope of the -build script. - -PSScriptAnalyzer may warn about variables assigned but not used -(PSUseDeclaredVarsMoreThanAssignments) when variables are declared in -Properties blocks. -This is a false positive - the variables ARE used -in tasks when the Properties scriptblock is dot-sourced at runtime. - -To suppress this warning, use script-scoped variables: - -Properties \{ - $script:build_dir = "c:\build" - $script:connection_string = "datasource=..." -\} +Properties scriptblocks are dot-sourced into each task's scope at +runtime. +Variables are not accessible outside of task scriptblocks. -This has identical runtime behavior but satisfies PSScriptAnalyzer's -static analysis requirements. -See the examples above for more details. +PSScriptAnalyzer may flag declared variables as unused — this is a +false positive. +Use the $script: prefix to suppress it (see examples). ## RELATED LINKS ## VERSION -*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.4](https://github.com/psake/psake).* diff --git a/docs/commands/Task.mdx b/docs/commands/Task.mdx index 16bbefc..0b1b254 100644 --- a/docs/commands/Task.mdx +++ b/docs/commands/Task.mdx @@ -49,9 +49,9 @@ Task [-Name] [[-Definition] ] [] ## DESCRIPTION -This function creates a 'task' object that will be used by the psake engine -to execute a build task. -Note: There must be at least one task called 'default' in the build script +Defines a named task in the build script. +Every script must include +at least one task named 'default'. ## EXAMPLES @@ -71,43 +71,9 @@ Task Clean { ``` -The 'default' task is required and should not contain an 'Action' parameter. -It uses the 'Depends' parameter to specify that 'Test' is a dependency - -The 'Test' task uses the 'Depends' parameter to specify that 'Compile' and -'Clean' are dependencies -The 'Compile' task depends on the 'Clean' task. - -Note: -The 'Action' parameter is defaulted to the script block following the -'Clean' task. - -An equivalent 'Test' task is shown below: - -Task Test -Depends Compile, Clean -Action \{ - $testMessage -\} - -The output for the above sample build script is shown below: - -Executing task, Clean... -Clean -Executing task, Compile... -Compile -Executing task, Test... -This is a test - -Build Succeeded! - ----------------------------------------------------------------------- -Build Time Report ----------------------------------------------------------------------- -Name Duration ----- -------- -Clean 00:00:00.0065614 -Compile 00:00:00.0133268 -Test 00:00:00.0225964 -Total: 00:00:00.0782496 +The trailing scriptblock is equivalent to -Action \{ ... +\}. +The 'default' task must exist and should declare no Action of its own. ## PARAMETERS @@ -195,19 +161,10 @@ HelpMessage: '' ### -Definition -A hashtable that can be used to define a task using a single parameter -instead of using multiple parameters. -This is an alternative to the normal -syntax of Task 'TaskName' -Action \{ ... -\} -Depends 'OtherTask' and allows -for a more declarative style of task definition. -The hashtable can contain -the following keys: -- Action -- PreAction -- PostAction -- PreCondition -- PostCondition +Declarative hashtable alternative to named parameters. +Supported keys: Action, PreAction, PostAction, PreCondition, +PostCondition, ContinueOnError, Description, Alias, +RequiredVariables. ```yaml Type: System.Collections.Hashtable @@ -570,4 +527,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS ## VERSION -*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.4](https://github.com/psake/psake).* diff --git a/docs/commands/TaskSetup.mdx b/docs/commands/TaskSetup.mdx index c5c2670..f1e5bc2 100644 --- a/docs/commands/TaskSetup.mdx +++ b/docs/commands/TaskSetup.mdx @@ -30,9 +30,10 @@ TaskSetup [-Setup] [] ## DESCRIPTION -This function will accept a scriptblock that will be executed before each task in the build script. - -The scriptblock accepts an optional parameter which describes the Task being setup. +Use this for per-task setup that applies across all tasks, such as +logging, timing, or environment checks. +The scriptblock receives the +current [PsakeTask] as an optional argument. ## EXAMPLES @@ -54,6 +55,7 @@ TaskSetup { The script above produces the following output: +``` Running 'TaskSetup' for task Clean Executing task, Clean... Running 'TaskSetup' for task Compile @@ -62,27 +64,25 @@ Running 'TaskSetup' for task Test Executing task, Test... Build Succeeded +``` ### EXAMPLE 2 ```powershell Task default -Depends Test -Task Test -Depends Compile, Clean { -} -Task Compile -Depends Clean { -} -Task Clean { -} +Task Test -Depends Compile, Clean {} +Task Compile -Depends Clean {} +Task Clean {} TaskSetup { param($task) + "Running 'TaskSetup' for task $($task.Name)" +} ``` -"Running 'TaskSetup' for task $($task.Name)" -\} - The script above produces the following output: +``` Running 'TaskSetup' for task Clean Executing task, Clean... Running 'TaskSetup' for task Compile @@ -91,12 +91,13 @@ Running 'TaskSetup' for task Test Executing task, Test... Build Succeeded +``` ## PARAMETERS ### -Setup -A scriptblock to execute +Receives the current task as an optional [PsakeTask] argument. ```yaml Type: System.Management.Automation.ScriptBlock @@ -131,4 +132,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS ## VERSION -*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.4](https://github.com/psake/psake).* diff --git a/docs/commands/TaskTearDown.mdx b/docs/commands/TaskTearDown.mdx index cdf506a..1d36873 100644 --- a/docs/commands/TaskTearDown.mdx +++ b/docs/commands/TaskTearDown.mdx @@ -30,11 +30,10 @@ TaskTearDown [-TearDown] [] ## DESCRIPTION -This function will accept a scriptblock that will be executed after each -task in the build script. - -The scriptblock accepts an optional parameter which describes the Task being -torn down. +Use this for per-task teardown such as logging duration, checking +postconditions, or cleaning up temporary state. +The completed +[PsakeTask] is passed as an optional argument with success/error info. ## EXAMPLES @@ -55,6 +54,7 @@ The script above produces the following output: ``` +``` Executing task, Clean... Running 'TaskTearDown' for task Clean Executing task, Compile... @@ -63,31 +63,29 @@ Executing task, Test... Running 'TaskTearDown' for task Test Build Succeeded +``` ### EXAMPLE 2 ```powershell Task default -Depends Test -Task Test -Depends Compile, Clean { -} -Task Compile -Depends Clean { -} -Task Clean { -} +Task Test -Depends Compile, Clean {} +Task Compile -Depends Clean {} +Task Clean {} TaskTearDown { param($task) -``` - - -if ($task.Success) \{ + if ($task.Success) { "Running 'TaskTearDown' for task $($task.Name) - success!" - \} else \{ + } else { "Running 'TaskTearDown' for task $($task.Name) - failed: $($task.ErrorMessage)" - \} -\} + } +} +``` + The script above produces the following output: +``` Executing task, Clean... Running 'TaskTearDown' for task Clean - success! Executing task, Compile... @@ -96,12 +94,13 @@ Executing task, Test... Running 'TaskTearDown' for task Test - success! Build Succeeded +``` ## PARAMETERS ### -TearDown -A scriptblock to execute +Receives the completed task as an optional [PsakeTask] argument. ```yaml Type: System.Management.Automation.ScriptBlock @@ -136,4 +135,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS ## VERSION -*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.4](https://github.com/psake/psake).* diff --git a/docs/commands/Test-BuildEnvironment.mdx b/docs/commands/Test-BuildEnvironment.mdx index d665e15..2430ceb 100644 --- a/docs/commands/Test-BuildEnvironment.mdx +++ b/docs/commands/Test-BuildEnvironment.mdx @@ -167,17 +167,18 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## OUTPUTS -### [bool] +### System.Boolean + +Returns $true if all required framework directories exist; +$false otherwise. -\{\{ Fill in the Description \}\} ### System.Boolean -\{\{ Fill in the Description \}\} ## NOTES ## RELATED LINKS ## VERSION -*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.4](https://github.com/psake/psake).* diff --git a/docs/commands/Test-PsakeTask.mdx b/docs/commands/Test-PsakeTask.mdx index bc6ccc9..43e8fa8 100644 --- a/docs/commands/Test-PsakeTask.mdx +++ b/docs/commands/Test-PsakeTask.mdx @@ -137,13 +137,11 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## NOTES -This function is intended for testing purposes and does not execute task -dependencies or pre/post actions. -It directly invokes the specified task's -Action scriptblock in isolation. +Dependencies, PreAction, and PostAction are skipped — only the +task's Action scriptblock is executed. ## RELATED LINKS ## VERSION -*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.4](https://github.com/psake/psake).* diff --git a/docs/commands/Version.mdx b/docs/commands/Version.mdx index 09bd17f..5194a31 100644 --- a/docs/commands/Version.mdx +++ b/docs/commands/Version.mdx @@ -90,4 +90,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS ## VERSION -*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).* +*This page was generated using comment-based help in [Psake 5.0.4](https://github.com/psake/psake).* diff --git a/scripts/New-DocusaurusModuleHelp.ps1 b/scripts/New-DocusaurusModuleHelp.ps1 index 88d96e6..9942769 100644 --- a/scripts/New-DocusaurusModuleHelp.ps1 +++ b/scripts/New-DocusaurusModuleHelp.ps1 @@ -139,6 +139,9 @@ function ConvertTo-DocusaurusMdx { $body = $body -replace '(?ms)^## ALIASES\r?\n\r?\nThis cmdlet has the following aliases,\r?\n \{\{Insert list of aliases\}\}\r?\n(\r?\n)?', '' # Remove the "Fill in the related links here" placeholder (keep real links if any). $body = $body -replace '\{\{ Fill in the related links here \}\}\r?\n', '' + # Remove "Fill in the Description" placeholders in INPUTS/OUTPUTS sections (PlatyPS generates + # these when .INPUTS/.OUTPUTS CBH is absent; real content on adjacent lines is preserved). + $body = $body -replace '\{\{ Fill in the Description \}\}\r?\n', '' # Warn about any remaining {{...}} placeholders — these indicate unfilled CBH fields. $remainingPlaceholders = [regex]::Matches($body, '\{\{[^}]+\}\}')