docs update

Author: Friedrich Weinmann

PSModuleDevelopment/changelog.md

@@ -2,6 +2,7 @@
 
 ## ???
 
+- New: Build Component - define build workflows based on pre-defined & extensible action code
 - Fix: TemplateStore - default path iss invalid on MAC (#136)
 - Fix: Invoke-PSMDTemplate - unreliable string replacement through -replace operator (#113)
 - Fix: Publish-PSMDScriptFile - insufficient exclude paths (#138; @Callidus2000)

PSModuleDevelopment/functions/build/Get-PSMDBuildAction.ps1

@@ -1,4 +1,21 @@
 function Get-PSMDBuildAction {
+<#
+	.SYNOPSIS
+		Get a list of registered build actions.
+	
+	.DESCRIPTION
+		Get a list of registered build actions.
+		Actions are the scriptblocks that are used to execute the build logic when running Invoke-PSMDBuildProject.
+	
+	.PARAMETER Name
+		The name by which to filter the actions returned.
+		Defaults to '*'
+	
+	.EXAMPLE
+		PS C:\> Get-PSMDBuildAction
+	
+		Get a list of all registered build actions.
+#>
 	[CmdletBinding()]
 	param (
 		[PsfArgumentCompleter('PSModuleDevelopment.Build.Action')]

PSModuleDevelopment/functions/build/Get-PSMDBuildArtifact.ps1

@@ -1,4 +1,36 @@
 function Get-PSMDBuildArtifact {
+<#
+	.SYNOPSIS
+		Retrieve an artifact during a build project's execution.
+	
+	.DESCRIPTION
+		Retrieve an artifact during a build project's execution.
+		These artifacts are usually created during such an execution and discarded once completed.
+	
+	.PARAMETER Name
+		The name by which to search for artifacts.
+		Defaults to '*'
+	
+	.PARAMETER Tag
+		Search for artifacts by tag.
+		Artifacts can receive tag for better categorization.
+		When specifying multiple tags, any artifact containing at least one of them will be returned.
+	
+	.EXAMPLE
+		PS C:\> Get-PSMDBuildArtifact
+	
+		List all available artifacts.
+	
+	.EXAMPLE
+		PS C:\> Get-PSMDBuildArtifact -Name ReleasePath
+	
+		Returns the artifact named "ReleasePath"
+	
+	.EXAMPLE
+		PS C:\> Get-PSMDBuildArtifact -Tag pssession
+	
+		Returns all artifacts with the tag "pssession"
+#>
 	[CmdletBinding()]
 	param (
 		[string]

PSModuleDevelopment/functions/build/Get-PSMDBuildProject.ps1

@@ -1,4 +1,30 @@
 function Get-PSMDBuildProject {
+<#
+	.SYNOPSIS
+		Reads & returns a build project.
+	
+	.DESCRIPTION
+		Reads & returns a build project.
+		A build project is a container including the steps executed during the build.
+	
+	.PARAMETER Path
+		Path to the build project file.
+		May target the folder, in which case the -Name parameter must be specified.
+	
+	.PARAMETER Name
+		The name of the build project to read.
+		Use together with the -Path parameter only.
+		Absolute file path assumed will be: "<Path>\<Name>.build.json"
+	
+	.PARAMETER Selected
+		Rather than specifying the path to read from, return the currently selected build project.
+		Use Select-PSMDBuildProject to select a build project as the default ("selected") project.
+	
+	.EXAMPLE
+		PS C:\> Get-PSMDBuildProject -Path 'C:\code\project' -Name project
+	
+		Will load the build project stored in the file "C:\code\project\project.build.json"
+#>
 	[CmdletBinding(DefaultParameterSetName = 'Path')]
 	param (
 		[Parameter(Mandatory = $true, ParameterSetName = 'Path')]

PSModuleDevelopment/functions/build/Get-PSMDBuildStep.ps1

@@ -1,4 +1,30 @@
 function Get-PSMDBuildStep {
+<#
+	.SYNOPSIS
+		Read the steps that are part of the specified build project.
+	
+	.DESCRIPTION
+		Read the steps that are part of the specified build project.
+	
+	.PARAMETER Name
+		The name by which to filter the steps returned.
+		Defaults to '*'
+	
+	.PARAMETER BuildProject
+		Path to the build project file to read from.
+		Defaults to the currently selected project if available.
+		Use Select-PSMDBuildProject to select a default project.
+	
+	.EXAMPLE
+		PS C:\> Get-PSMDBuildStep
+	
+		Read all steps that are part of the default build project.
+	
+	.EXAMPLE
+		PS C:\> Get-PSMDBuildStep -Name CreateSession -BuildProject C:\code\Project\Project.build.json
+	
+		Return the CreateSession step from the specified project file.
+#>
 	[CmdletBinding()]
 	param (
 		[string]

PSModuleDevelopment/functions/build/Select-PSMDBuildProject.ps1

@@ -1,20 +1,40 @@
 function Select-PSMDBuildProject
 {
-	[CmdletBinding()]
-	Param (
+<#
+	.SYNOPSIS
+		Set the specified build project as the default project.
 	
-	)
+	.DESCRIPTION
+		Set the specified build project as the default project.
+		This will have most other commands in this Component automatically use the specified project.
 	
-	begin
-	{
+	.PARAMETER Path
+		Path to the project file to pick.
+	
+	.PARAMETER Register
+		Persist the choice as default build project file across PowerShell sessions.
+	
+	.EXAMPLE
+		PS C:\> Select-PSMDBuildProject -Path 'c:\code\Project\Project.build.json'
+	
+		Sets the specified build project as the default project.
+#>
+	[CmdletBinding()]
+	param (
+		[Parameter(Mandatory = $true)]
+		[string]
+		$Path,
 
-	}
-	process
-	{
+		[switch]
+		$Register
+	)
 
-	}
-	end
+	process
 	{
-	
+		Invoke-PSFProtectedCommand -ActionString 'Select-PSMDBuildProject.Testing' -ActionStringValues $Path -ScriptBlock {
+			$null = Get-PSMDBuildProject -Path $Path -ErrorAction Stop
+		} -Target $Path -EnableException $true -PSCmdlet $PSCmdlet
+		Set-PSFConfig -Module PSModuleDevelopment -Name 'Build.Project.Selected' -Value $Path
+		if ($Register) { Register-PSFConfig -Module PSModuleDevelopment -Name 'Build.Project.Selected' }
 	}
 }