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/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..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,29 +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. + # 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 } @@ -51,6 +62,16 @@ 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)) + $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..445148e 100644 --- a/docs/commands/Assert.mdx +++ b/docs/commands/Assert.mdx @@ -22,9 +22,10 @@ Helper function for "Design by Contract" assertion checking. ## SYNTAX -```powershell -Assert [-conditionToCheck] [-failureMessage] [-ProgressAction ] - [] +### __AllParameterSets + +``` +Assert [-ConditionToCheck] [-FailureMessage] [] ``` ## DESCRIPTION @@ -39,6 +40,7 @@ This is a helper function that makes the code less noisy by eliminating many of Assert $false "This always throws an exception" ``` + Example of an assertion that will always fail. ### EXAMPLE 2 @@ -47,11 +49,12 @@ Example of an assertion that will always fail. 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 +68,54 @@ 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 +### -FailureMessage -The error message used for the exception if the conditionToCheck parameter is false +The error message used for the exception if the ConditionToCheck parameter is false ```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: True -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 +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 +125,5 @@ 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) - -[TaskTearDown](TaskTearDown.mdx) - ## 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 new file mode 100644 index 0000000..958dba7 --- /dev/null +++ b/docs/commands/BuildSetup.mdx @@ -0,0 +1,104 @@ +--- +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). +::: + +:::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 + +### __AllParameterSets + +``` +BuildSetup [-Setup] [] +``` + +## 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: 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, -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 + +## 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 new file mode 100644 index 0000000..63bdef8 --- /dev/null +++ b/docs/commands/BuildTearDown.mdx @@ -0,0 +1,129 @@ +--- +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). +::: + +:::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 + +### __AllParameterSets + +``` +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 + +## 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: 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, -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 + +## 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 new file mode 100644 index 0000000..29f4a4d --- /dev/null +++ b/docs/commands/Clear-PsakeCache.mdx @@ -0,0 +1,124 @@ +--- +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). +::: + +:::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 + +### __AllParameterSets + +``` +Clear-PsakeCache [[-Path] ] [[-TaskName] ] [] +``` + +## 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: 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: 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, -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 + +- [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/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/Execute.mdx b/docs/commands/Execute.mdx new file mode 100644 index 0000000..0cdca46 --- /dev/null +++ b/docs/commands/Execute.mdx @@ -0,0 +1,233 @@ +--- +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). +::: + +:::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 + +### __AllParameterSets + +``` +Execute [-Cmd] [[-ErrorMessage] ] [[-MaxRetries] ] + [[-RetryTriggerErrorPattern] ] [[-WorkingDirectory] ] [[-TimeoutSeconds] ] + [-NewProcess] [] +``` + +## 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: 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: '' +``` + +### -ErrorMessage + +The error message to display if the external command returned a non-zero +exit code. + +```yaml +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: '' +``` + +### -MaxRetries + +The maximum number of times to retry the command before failing. + +```yaml +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: '' +``` + +### -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: 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: '' +``` + +### -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: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 3 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -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: System.Int32 +DefaultValue: 300 +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 5 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -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, -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 + +## 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..e50c43d 100644 --- a/docs/commands/FormatTaskName.mdx +++ b/docs/commands/FormatTaskName.mdx @@ -22,8 +22,10 @@ This function allows you to change how psake renders the task name during a buil ## SYNTAX -```powershell -FormatTaskName [-format] [-ProgressAction ] [] +### __AllParameterSets + +``` +FormatTaskName [-Format] [] ``` ## DESCRIPTION @@ -38,20 +40,21 @@ This function takes either a string which represents a format string (formats us 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: @@ -71,6 +74,7 @@ Build Succeeded! A sample build script that uses a ScriptBlock is shown below: ``` + Task default -depends TaskA, TaskB, TaskC FormatTaskName \{ @@ -79,15 +83,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 +101,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 +137,5 @@ 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) - -[TaskTearDown](TaskTearDown.mdx) - ## 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..9f5ad3d 100644 --- a/docs/commands/Framework.mdx +++ b/docs/commands/Framework.mdx @@ -22,15 +22,21 @@ Sets the version of the .NET framework you want to use during build. ## SYNTAX -```powershell -Framework [-framework] [-ProgressAction ] [] +### __AllParameterSets + +``` +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. +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 @@ -38,54 +44,44 @@ Default is '3.5*', where x86 or x64 will be detected based on the bitness of the ```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 ## 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 +91,5 @@ 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) - -[TaskTearDown](TaskTearDown.mdx) - ## 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..5a854f8 100644 --- a/docs/commands/Get-PSakeScriptTasks.mdx +++ b/docs/commands/Get-PSakeScriptTasks.mdx @@ -22,8 +22,10 @@ Returns meta data about all the tasks defined in the provided psake script. ## SYNTAX -```powershell -Get-PSakeScriptTasks [[-buildFile] ] [-ProgressAction ] [] +### __AllParameterSets + +``` +Get-PSakeScriptTasks [[-BuildFile] ] [] ``` ## DESCRIPTION @@ -35,9 +37,10 @@ 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 --------- ----- ---- ----------- \{\} Compile @@ -49,41 +52,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 +88,5 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -[Invoke-psake](Invoke-psake.mdx) - ## 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 new file mode 100644 index 0000000..3fa2102 --- /dev/null +++ b/docs/commands/Get-PsakeBuildPlan.mdx @@ -0,0 +1,150 @@ +--- +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). +::: + +:::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 + +### __AllParameterSets + +``` +Get-PsakeBuildPlan [[-BuildFile] ] [[-TaskList] ] [] +``` + +## 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: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -TaskList + +A list of task names to include in the plan. +Defaults to 'default'. + +```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 + +## OUTPUTS + +## NOTES + +## RELATED LINKS + +## 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 65f816e..9e429a1 100644 --- a/docs/commands/Include.mdx +++ b/docs/commands/Include.mdx @@ -18,112 +18,126 @@ 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] [] ``` ## 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 { +} ``` -Include ".\build_utils.ps1" -Task default -depends Test +The script above includes all the functions and variables defined in the ".\build_utils.ps1" script into the current build script's scope -Task Test -depends Compile, Clean \{ -\} +Note: You can have more than 1 "Include" function defined in the build script. -Task Compile -depends Clean \{ -\} +### EXAMPLE 2 -Task Clean \{ -\} +```powershell +@("File1.ps1","File2.ps1") | Include +Get-ChildItem | Include +``` ------------ -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. +Strings or FileInfo objects can be piped to the Include function ## PARAMETERS -### -fileNamePathToInclude +### -LiteralPath -A string containing the path and name of the powershell file to include +A string containing the path and name of the powershell file to include (no +wildcards) ```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: LiteralPath + Position: 0 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: true + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' ``` -### -ProgressAction +### -Path -\{\{ Fill ProgressAction Description \}\} +A string containing the path and name of the powershell file to include +(wildcards can be used) ```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: 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) - -[TaskTearDown](TaskTearDown.mdx) - ## 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 new file mode 100644 index 0000000..ed21aa4 --- /dev/null +++ b/docs/commands/Invoke-Psake.mdx @@ -0,0 +1,459 @@ +--- +id: Invoke-Psake +title: Invoke-Psake +description: Help page for the PowerShell Psake "Invoke-Psake" 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 psake build script. + +## SYNTAX + +### __AllParameterSets + +``` +Invoke-Psake [[-BuildFile] ] [[-TaskList] ] [[-Framework] ] [-Docs] + [[-Parameters] ] [[-Properties] ] [[-Initialization] ] [-NoLogo] + [-DetailedDocs] [-NoTimeReport] [-OutputFormat ] [-NoCache] [-CompileOnly] [-Quiet] + [-BuildPlan ] [] +``` + +## DESCRIPTION + +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 '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 +during the execution phase. + +### EXAMPLE 5 + +```powershell +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: '' +``` + +### -BuildPlan + +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. + +```yaml +Type: PsakeBuildPlan +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: true + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -CompileOnly + +Return the build plan without executing any tasks. +Delegates to +Get-PsakeBuildPlan. +Useful for tooling and testing. + +```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: '' +``` + +### -DetailedDocs + +Prints a more descriptive list of tasks and their descriptions. + +```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: '' +``` + +### -Docs + +Prints a list of tasks and their descriptions + +```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: '' +``` + +### -Framework + +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' + +```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: '' +``` + +### -Initialization + +A script block that will be executed before the tasks are executed. + +```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: '' +``` + +### -NoCache + +Bypass task caching. +All tasks will execute regardless of cache state. + +```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: '' +``` + +### -NoLogo + +Do not display the startup banner and copyright message. + +```yaml +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: '' +``` + +### -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: '' +``` + +### -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. + +```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: '' +``` + +### -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: System.Collections.Hashtable +DefaultValue: '@{}' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 4 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Properties + +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. + +```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: '' +``` + +### -Quiet + +Suppress all console output. +The PsakeBuildResult is still returned. + +```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: '' +``` + +### -TaskList + +A comma-separated list of task names to execute + +```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 + +## 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 328c348..0eba097 100644 --- a/docs/commands/Invoke-Task.mdx +++ b/docs/commands/Invoke-Task.mdx @@ -22,13 +22,16 @@ Executes another task in the current build script. ## SYNTAX -```powershell -Invoke-Task [-taskName] [-ProgressAction ] [] +### __AllParameterSets + +``` +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. +This is a function that will allow you to invoke a Task from within another +Task in the current build script. ## EXAMPLES @@ -38,45 +41,38 @@ This is a function that will allow you to invoke a Task from within another Task 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 +82,5 @@ 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) - -[TaskTearDown](TaskTearDown.mdx) - ## 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 deleted file mode 100644 index 4b02b36..0000000 --- a/docs/commands/Invoke-psake.mdx +++ /dev/null @@ -1,193 +0,0 @@ ---- -id: Invoke-psake -title: Invoke-psake -description: Help page for the PowerShell Psake "Invoke-psake" 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 psake build script. - -## SYNTAX - -```powershell -Invoke-psake [[-buildFile] ] [[-taskList] ] [[-framework] ] [-docs] - [[-parameters] ] [[-properties] ] [[-initialization] ] [-nologo] - [-detailedDocs] [-notr] [-ProgressAction ] [] -``` - -## DESCRIPTION - -This function runs a psake build script - -## EXAMPLES - -### EXAMPLE 1 - -```powershell -Invoke-psake -``` - -Runs the 'default' task in the '.build.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 Tests -``` - -This example will run the 'Tests' tasks in the 'psakefile.ps1' build script. -The 'psakefile.ps1' is assumed to be in the current directory. - -### EXAMPLE 4 - -```powershell -Invoke-psake 'Tests, Package' -``` - -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. - -### EXAMPLE 5 - -```powershell -Invoke-psake .\build.ps1 -docs -``` - -Prints a report of all the tasks and their dependencies and descriptions and then exits - -### EXAMPLE 6 - -```powershell -Invoke-psake .\parameters.ps1 -parameters @{"p1"="v1";"p2"="v2"} -``` - -Runs the build script called 'parameters.ps1' and passes in parameters 'p1' and 'p2' with values 'v1' and 'v2' - -Here's the .\parameters.ps1 build script: - -properties \{ - $my_property = $p1 + $p2 -\} - -task default -depends TestParams - -task TestParams \{ - Assert ($my_property -ne $null) '$my_property should not be null' -\} - -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". - -### EXAMPLE 7 - -```powershell -Invoke-psake .\properties.ps1 -properties @{"x"="1";"y"="2"} -``` - -Runs the build script called 'properties.ps1' and passes in parameters 'x' and 'y' with values '1' and '2' - -This feature allows you to override existing properties in your build script. - -Here's the .\properties.ps1 build script: - -properties \{ - $x = $null - $y = $null - $z = $null -\} - -task default -depends TestProperties - -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" -\} - -## PARAMETERS - -### -buildFile - -The path to the psake build script to execute - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: False -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -taskList - -A comma-separated list of task names to execute - -```yaml -Type: String[] -Parameter Sets: (All) -Aliases: - -Required: False -Position: 2 -Default value: @() -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -framework - -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: String -Parameter Sets: (All) -Aliases: - -Required: False -Position: 3 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -docs - -Prints a list of tasks and their descriptions - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: - -Required: False -Position: 4 -Default value: False -Acc diff --git a/docs/commands/Properties.mdx b/docs/commands/Properties.mdx index 23e8d9a..e49dcb5 100644 --- a/docs/commands/Properties.mdx +++ b/docs/commands/Properties.mdx @@ -18,81 +18,137 @@ 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] [] ``` ## 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 \{ +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 \{ -\} +Note: You can have more than one "Properties" function defined in the build script. -Task Clean \{ -\} +### EXAMPLE 2 -Note: You can have more than one "Properties" function defined in the build script. +```powershell +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 +} +``` + + +Recommended: Use script-scoped variables to avoid PSScriptAnalyzer warnings +The $script: prefix has identical runtime behavior but satisfies +PSScriptAnalyzer's static analysis requirements. + +### EXAMPLE 3 + +```powershell +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) + +Variables still work correctly at runtime, but PSScriptAnalyzer cannot detect +that they will be used in tasks. ## PARAMETERS -### -properties +### -Hashtable -The script block containing all the variable assignment statements +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: ScriptBlock -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False +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: '' ``` -### -ProgressAction +### -Properties -\{\{ Fill ProgressAction Description \}\} +The script block containing all the variable assignment statements ```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: 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 +156,33 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## NOTES -## RELATED LINKS - -[Assert](Assert.mdx) - -[Exec](Exec.mdx) - -[FormatTaskName](FormatTaskName.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. -[Framework](Framework.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. -[Get-PSakeScriptTasks](Get-PSakeScriptTasks.mdx) +To suppress this warning, use script-scoped variables: -[Include](Include.mdx) - -[Invoke-psake](Invoke-psake.mdx) +Properties \{ + $script:build_dir = "c:\build" + $script:connection_string = "datasource=..." +\} -[Task](Task.mdx) +This has identical runtime behavior but satisfies PSScriptAnalyzer's +static analysis requirements. +See the examples above for more details. -[TaskSetup](TaskSetup.mdx) -[TaskTearDown](TaskTearDown.mdx) +## RELATED LINKS ## 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..16bbefc 100644 --- a/docs/commands/Task.mdx +++ b/docs/commands/Task.mdx @@ -24,26 +24,33 @@ 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] ] [] ``` ## 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 @@ -51,31 +58,29 @@ Note: There must be at least one task called 'default' in the build script ### EXAMPLE 1 ```powershell -A sample build script is shown below: -``` - 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 -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 +111,463 @@ 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 -Parameter Sets: (All) -Aliases: +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: '' +``` + +### -Alias -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False +An alternate name 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: '' ``` -### -action +### -ContinueOnError -A scriptblock containing the statements to execute for the task. +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: ScriptBlock -Parameter Sets: (All) -Aliases: +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: '' +``` + +### -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 -Required: False -Position: 2 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False +```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: '' ``` -### -preaction +### -Depends -A scriptblock to be executed before the 'Action' scriptblock. -Note: This parameter is ignored if the 'Action' scriptblock is not defined. +An array of task names that this task depends on. +These tasks will be executed before the current task is executed. ```yaml -Type: ScriptBlock -Parameter Sets: (All) -Aliases: +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: '' +``` + +### -Description + +A description of 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: '' +``` + +### -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: '' +``` + +### -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. -Required: False -Position: 3 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False +```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: '' +``` + +### -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: '' ``` -### -postaction +### -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: '' +``` + +### -Name + +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: '' +``` + +### -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 -Parameter Sets: (All) -Aliases: +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: '' +``` + +### -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: '' +``` + +### -PreAction + +A scriptblock to be executed before the 'Action' scriptblock. +Note: This parameter is ignored if the 'Action' scriptblock is not defined. -Required: False -Position: 4 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False +```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: '' ``` -### -precondition +### -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 -Parameter Sets: (All) +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: '' +``` + +### -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: '' +``` + +### -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 -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..c5c2670 100644 --- a/docs/commands/TaskSetup.mdx +++ b/docs/commands/TaskSetup.mdx @@ -22,8 +22,10 @@ Adds a scriptblock that will be executed before each task ## SYNTAX -```powershell -TaskSetup [-setup] [-ProgressAction ] [] +### __AllParameterSets + +``` +TaskSetup [-Setup] [] ``` ## DESCRIPTION @@ -37,23 +39,18 @@ 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 Compile -Depends Clean { +} +Task Clean { +} +TaskSetup { + "Running 'TaskSetup' for task $context.Peek().currentTaskName" +} ``` -Task default -depends Test - -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: @@ -69,24 +66,19 @@ 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 Compile -Depends Clean { +} +Task Clean { +} +TaskSetup { + param($task) ``` -Task default -depends Test - -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: @@ -102,41 +94,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 +130,5 @@ 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) - -[TaskTearDown](TaskTearDown.mdx) - ## 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..cdf506a 100644 --- a/docs/commands/TaskTearDown.mdx +++ b/docs/commands/TaskTearDown.mdx @@ -22,40 +22,38 @@ Adds a scriptblock to the build that will be executed after each task ## SYNTAX -```powershell -TaskTearDown [-teardown] [-ProgressAction ] [] +### __AllParameterSets + +``` +TaskTearDown [-TearDown] [] ``` ## 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 Compile -depends Clean \{ -\} - -Task Clean \{ -\} - -TaskTearDown \{ +Task default -Depends Test +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 @@ -69,24 +67,19 @@ 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 Compile -Depends Clean { +} +Task Clean { +} +TaskTearDown { + param($task) ``` -Task default -depends Test - -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 \{ "Running 'TaskTearDown' for task $($task.Name) - failed: $($task.ErrorMessage)" @@ -106,41 +99,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 +135,5 @@ 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) - ## 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 new file mode 100644 index 0000000..d665e15 --- /dev/null +++ b/docs/commands/Test-BuildEnvironment.mdx @@ -0,0 +1,183 @@ +--- +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). +::: + +:::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 +current machine. + +## SYNTAX + +### Framework (Default) + +``` +Test-BuildEnvironment [[-Framework] ] [] +``` + +### BuildFile + +``` +Test-BuildEnvironment -BuildFile [] +``` + +## 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 + +### -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: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: BuildFile + Position: Named + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -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, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +### [bool] + +\{\{ 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).* diff --git a/docs/commands/Test-PsakeTask.mdx b/docs/commands/Test-PsakeTask.mdx new file mode 100644 index 0000000..bc6ccc9 --- /dev/null +++ b/docs/commands/Test-PsakeTask.mdx @@ -0,0 +1,149 @@ +--- +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). +::: + +:::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 + +### __AllParameterSets + +``` +Test-PsakeTask [[-BuildFile] ] [-TaskName] [[-Variables] ] + [] +``` + +## 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: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -TaskName + +The name of the task to execute. + +```yaml +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: 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, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://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.3](https://github.com/psake/psake).* diff --git a/docs/commands/Version.mdx b/docs/commands/Version.mdx new file mode 100644 index 0000000..09bd17f --- /dev/null +++ b/docs/commands/Version.mdx @@ -0,0 +1,93 @@ +--- +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). +::: + +:::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 + +### __AllParameterSets + +``` +Version [-RequiredVersion] [] +``` + +## 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: System.Int32 +DefaultValue: 0 +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, -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 + +## VERSION +*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 53b0a0f..80a885a 100644 --- a/docs/commands/docusaurus.sidebar.js +++ b/docs/commands/docusaurus.sidebar.js @@ -1,24 +1,27 @@ /** * 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-DocusaurusModuleHelp using Microsoft.PowerShell.PlatyPS. */ module.exports = [ 'commands/Assert', - 'commands/Exec', + 'commands/BuildSetup', + 'commands/BuildTearDown', + 'commands/Clear-PsakeCache', + 'commands/Execute', 'commands/FormatTaskName', 'commands/Framework', + 'commands/Get-PsakeBuildPlan', 'commands/Get-PSakeScriptTasks', 'commands/Include', - 'commands/Invoke-psake', + 'commands/Invoke-Psake', 'commands/Invoke-Task', 'commands/Properties', 'commands/Task', 'commands/TaskSetup', - 'commands/TaskTearDown' -]; + 'commands/TaskTearDown', + 'commands/Test-BuildEnvironment', + 'commands/Test-PsakeTask', + 'commands/Version' +]; \ No newline at end of file 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/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/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/psakeFile.ps1 b/psakeFile.ps1 index f12a766..44282d0 100644 --- a/psakeFile.ps1 +++ b/psakeFile.ps1 @@ -1,29 +1,24 @@ -#require -Version 7 +#requires -Version 7 +Version 5 + $ErrorView = 'Detailed' -Version 5 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). @@ -33,8 +28,45 @@ 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)" + 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 $docusaurusOptions.DocsFolder $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:docsOutputFolder = Join-Path -Path $docusaurusOptions.DocsFolder -ChildPath $docusaurusOptions.Sidebar | Join-Path -ChildPath "*.*" + $script:psbOutputFolder = Join-Path $psbOptions.DocsFolder $psbOptions.Sidebar | Join-Path -ChildPath '*.*' } FormatTaskName { @@ -45,103 +77,127 @@ 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' + Action = { Exec { bun install } } } -Task Build -Depends Init, GenerateCommandReference, FrontMatterCMSSync { - Exec { bun run build } +Task 'Build' @{ + Description = 'Full production site build.' + DependsOn = @('Init', 'GenerateCommandReference', 'GenerateCommandReferencePSB', '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" +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' + } } } -(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 -# 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." - 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" -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 +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 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 +#region PSB Command Reference Generation Tasks +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 'GenerateCommandReferencePSB-Clean' @{ + Action = { + Write-Host 'Removing existing PSB MDX files' -ForegroundColor Magenta + if (Test-Path -Path $script:psbOutputFolder) { + Remove-Item -Path $script:psbOutputFolder } - $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 '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 '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 ab180c2..e18ec42 100644 --- a/requirements.psd1 +++ b/requirements.psd1 @@ -7,15 +7,16 @@ Parameters = @{ SkipPublisherCheck = $true } + Import = $false } 'psake' = @{ - Version = '5.0.3' + Version = 'latest' } - 'PlatyPS' = @{ - Version = '0.14.2' + 'Microsoft.PowerShell.PlatyPS' = @{ + Version = 'latest' } - 'Alt3.Docusaurus.Powershell' = @{ - Version = '1.0.36' + 'PowerShellBuild' = @{ + Version = 'latest' } 'Yayaml' = @{ Version = '0.6.0' diff --git a/scripts/New-DocusaurusModuleHelp.ps1 b/scripts/New-DocusaurusModuleHelp.ps1 new file mode 100644 index 0000000..88d96e6 --- /dev/null +++ b/scripts/New-DocusaurusModuleHelp.ps1 @@ -0,0 +1,283 @@ +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 = @{} + ) + + 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 + + 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. +::: +"@ + } + + $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 + 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 = '', + [string] $SideBar = 'commands' + ) + + $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 + + # 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) + $body = $body -replace "\[$escaped\]\(\)", "[$cmd](/docs/$SideBar/$cmd)" + } + $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 + + # 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) + + # 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)', + { + 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 '' +} 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