Add Microsoft.PowerShell.PlatyPS documentation

.build/tasks/generateHelp.Microsoft.PowerShell.PlatyPS.build.ps1

@@ -0,0 +1,155 @@
+param
+(
+    [Parameter()]
+    [System.IO.DirectoryInfo]
+    $ProjectPath = (property ProjectPath $BuildRoot),
+
+    [Parameter()]
+    [System.String]
+    $ProjectName = (property ProjectName ''),
+
+    [Parameter()]
+    [System.String]
+    $SourcePath = (property SourcePath ''),
+
+    [Parameter()]
+    [System.String]
+    $HelpSourceFolder = (property HelpSourceFolder 'docs'),
+
+    [Parameter()]
+    [System.String]
+    $OutputDirectory = (property OutputDirectory 'output'),
+
+    [Parameter()]
+    [System.String]
+    $BuiltModuleSubdirectory = (property BuiltModuleSubdirectory ''),
+
+    [Parameter()]
+    [System.Management.Automation.SwitchParameter]
+    $VersionedOutputDirectory = (property VersionedOutputDirectory $true),
+
+    [Parameter()]
+    [System.String]
+    $HelpOutputFolder = (property HelpOutputFolder 'help'),
+
+    [Parameter()]
+    [cultureInfo]
+    $HelpCultureInfo = 'en-US',
+
+    [Parameter()]
+    [System.Management.Automation.SwitchParameter]
+    $CopyHelpMamlToBuiltModuleBase = (property CopyHelpMamlToBuiltModuleBase $true),
+
+    # Build Configuration object
+    [Parameter()]
+    [System.Collections.Hashtable]
+    $BuildInfo = (property BuildInfo @{ })
+)
+
+function Get-GenerateHelpPSVariables
+{
+    param ()
+
+    $script:PesterOutputFolder = Get-SamplerAbsolutePath -Path $PesterOutputFolder -RelativeTo $OutputDirectory
+
+    "`tPester Output Folder       = '$PesterOutputFolder"
+
+    $script:HelpSourceFolder = Get-SamplerAbsolutePath -Path $HelpSourceFolder -RelativeTo $ProjectPath
+    "`tHelp Source Folder         = '$HelpSourceFolder'"
+
+    $script:HelpOutputFolder =  Get-SamplerAbsolutePath -Path $HelpOutputFolder -RelativeTo $OutputDirectory
+    "`tHelp output Folder         = '$HelpOutputFolder'"
+
+    if ($ModuleVersion)
+    {
+        $script:HelpOutputVersionFolder = Get-SamplerAbsolutePath -Path $ModuleVersion -RelativeTo $HelpOutputFolder
+    }
+
+    "`tHelp output Version Folder = '$HelpOutputVersionFolder'"
+
+    $script:HelpOutputCultureFolder = Get-SamplerAbsolutePath -Path $HelpCultureInfo -RelativeTo $HelpOutputVersionFolder
+    "`tHelp output Culture path   = '$HelpOutputCultureFolder'"
+
+    $script:DocOutputFolder = Get-SamplerAbsolutePath -Path 'docs' -RelativeTo $OutputDirectory
+    "`tDocs output folder path    = '$DocOutputFolder'"
+}
+
+# Synopsis: Produces markdown help files from the built module.
+task Generate_help_from_built_module {
+    . Set-SamplerTaskVariable
+
+    Get-GenerateHelpPSVariables
+
+    $generateHelpCommands = @"
+    `$env:PSModulePath = '$Env:PSModulePath'
+    `$targetModule = Import-Module -Name '$ProjectName' -ErrorAction Stop -Passthru
+
+    `$helpDestination = Join-Path '$HelpSourceFolder' -ChildPath '$HelpCultureInfo'
+
+    if (!(Test-Path -Path `$helpDestination)) {
+        New-Item -Path `$helpDestination -ItemType Directory -Force -ErrorAction Ignore | Out-Null
+    }
+
+    `$docOutputFolder = Join-Path '$DocOutputFolder' -ChildPath '$ProjectName'
+
+    `$commandsArray = @()
+    foreach (`$publicFunction in `$targetModule.ExportedFunctions.Keys) {
+        `$command = Get-Command -Name `$publicFunction -Module `$targetModule
+
+        `$newMarkdownCommandHelpParams = @{
+            CommandInfo  = `$command
+            OutputFolder = '$DocOutputFolder'
+            HelpVersion  = `$targetModule.Version
+            Locale       = '$HelpCultureInfo'
+            Encoding     = 'utf8'
+            Force        = `$true
+        }
+        `$Output = New-MarkdownCommandHelp @newMarkdownCommandHelpParams
+
+        `$helpCommand = Import-MarkdownCommandHelp -Path `$Output -ErrorAction Ignore
+
+        # Add the command to the array
+        `$commandsArray += `$helpCommand
+
+        # Known issue: https://github.com/PowerShell/platyPS/issues/735
+        `$whatIf = `$helpCommand.Parameters | Where-Object -Property Name -EQ 'WhatIf'
+        if (`$whatIf) {
+            (`$helpCommand.Parameters | Where-Object -Property Name -EQ 'WhatIf').Description = 'Tells PowerShell to run the command in a mode that only reports what would happen, but not actually let the command run or make changes.'
+        }
+
+        `$confirm = `$helpCommand.Parameters | Where-Object -Property Name -EQ 'Confirm'
+        if (`$confirm) {
+            (`$helpCommand.Parameters | Where-Object -Property Name -EQ 'Confirm').Description = 'Prompts you for confirmation before running the cmdlet.'
+        }
+
+        `$alias = Get-Alias -Definition `$command.Name -ErrorAction Ignore
+
+        if (`$alias) {
+            `$helpCommand.Aliases = @(`$alias.Name)
+        } else {
+            `$helpCommand.Aliases = @()
+        }
+
+        `$helpCommand | Export-MarkdownCommandHelp -OutputFolder '$DocOutputFolder' -Force
+
+        Copy-Item -Path `$Output -Destination `$helpDestination -Force
+    }
+
+    `$newMarkdownModuleFileParams = @{
+        CommandHelp  = `$commandsArray
+        OutputFolder = '$DocOutputFolder'
+        Force        = `$true
+    }
+    `$markdownFile = New-MarkdownModuleFile @newMarkdownModuleFileParams
+
+    if (`$markdownFile) {
+        Copy-Item -Path `$markdownFile -Destination `$helpDestination -Force
+    }
+
+"@
+    Write-Build -Color DarkGray -Text "$generateHelpCommands"
+    $sb = [ScriptBlock]::create($generateHelpCommands)
+
+    $pwshPath = (Get-Process -Id $PID).Path
+    &$pwshPath -Command $sb -ExecutionPolicy 'ByPass'
+}

CONTRIBUTING.md

@@ -36,7 +36,7 @@ The workflow for using this and developing the code is shown below.
 
 3. Start a fresh new PowerShell session to avoid anythjing from your current working sessions to interfere with the module development and building. Develop your updates in the source directory.
 
-You should also resolve all dependencies before you start developing. This will ensure that you have all the required modules, and only them, installed and loaded into your session.
+   You should also resolve all dependencies before you start developing. This will ensure that you have all the required modules, and only them, installed and loaded into your session.
 
    ```PowerShell
    .\build.ps1 -ResolveDependency -Tasks noop -UsePSResourceGet
@@ -105,7 +105,14 @@ You should also resolve all dependencies before you start developing. This will
    ### Fixed
    - Fixed issue with `New-FabricDataPipeline` not working correctly.
    ```
-9. Once you are happy with your code and you have updated the changelog, push your branch to GitHub and create a PR against the repo.
+
+10. Once you are happy with your code and you have updated the changelog, there is one thing left to do, which is documentation. To run the generation of the documentation, the `build.ps1` can leverage the `Generate_help_from_built_module` task:
+
+   ```powershell
+   ./build.ps1 -Tasks Generate_help_from_built_module
+   ```
+
+11. When the process finishes, the documentation should be updated. Now push your branch to GitHub and create a PR against the repo.
 
 ## Thanks!
 

RequiredModules.psd1

@@ -11,17 +11,23 @@
     #        Repository = 'PSGallery'
     #    }
     #}
-    Assert = "0.9.6"
-    InvokeBuild                 = 'latest'
-    PSScriptAnalyzer            = '1.19.1'
-    Pester                      = 'latest'
-    ModuleBuilder               = 'latest'
-    ChangelogManagement         = 'latest'
-    Sampler                     = 'latest'
-    'Sampler.GitHubTasks'       = 'latest'
-    MarkdownLinkCheck           = 'latest'
-    PSFramework                = 'latest'
-    'Az.Accounts'              = '5.0.0'
-    'Az.Resources'             = '6.15.1'
-    'MicrosoftPowerBIMgmt'     = '1.2.1111'
+    Assert                         = "0.9.6"
+    InvokeBuild                    = 'latest'
+    PSScriptAnalyzer               = '1.19.1'
+    Pester                         = 'latest'
+    ModuleBuilder                  = 'latest'
+    ChangelogManagement            = 'latest'
+    Sampler                        = 'latest'
+    'Sampler.GitHubTasks'          = 'latest'
+    MarkdownLinkCheck              = 'latest'
+    PSFramework                    = 'latest'
+    'Az.Accounts'                  = '5.0.0'
+    'Az.Resources'                 = '6.15.1'
+    'MicrosoftPowerBIMgmt'         = '1.2.1111'
+    'Microsoft.PowerShell.PlatyPS' = @{
+        Version    = '1.0.0-preview5'
+        Parameters = @{
+            AllowPrerelease = $true
+        } # TODO: Simply remove after GA
+    }
 }

build.yaml

@@ -52,7 +52,6 @@ BuildWorkflow:
     - Build_NestedModules_ModuleBuilder
     - Create_changelog_release_output
 
-
   pack:
     - build
     - package_module_nupkg

docs/en-US/Add-FabricDomainWorkspaceAssignmentByCapacity.md

@@ -0,0 +1,110 @@
+---
+document type: cmdlet
+external help file: FabricTools-Help.xml
+HelpUri: ''
+Locale: en-US
+Module Name: FabricTools
+ms.date: 07/14/2025
+PlatyPS schema version: 2024-05-01
+title: Add-FabricDomainWorkspaceAssignmentByCapacity
+---
+
+# Add-FabricDomainWorkspaceAssignmentByCapacity
+
+## SYNOPSIS
+
+Assigns workspaces to a Fabric domain based on specified capacities.
+
+## SYNTAX
+
+### __AllParameterSets
+
+```
+Add-FabricDomainWorkspaceAssignmentByCapacity [-DomainId] <guid> [-CapacitiesIds] <guid[]>
+ [<CommonParameters>]
+```
+
+## ALIASES
+
+Assign-FabricDomainWorkspaceByCapacity
+
+## DESCRIPTION
+
+The `Add-FabricDomainWorkspaceAssignmentByCapacity` function assigns workspaces to a Fabric domain using a list of capacity IDs by making a POST request to the relevant API endpoint.
+
+## EXAMPLES
+
+### EXAMPLE 1
+
+Assigns workspaces to the domain with ID "12345" based on the specified capacities.
+
+```powershell
+Add-FabricDomainWorkspaceAssignmentByCapacity -DomainId "12345" -CapacitiesIds @("capacity1", "capacity2")
+```
+
+## PARAMETERS
+
+### -CapacitiesIds
+
+An array of capacity IDs used to assign workspaces to the domain.
+
+```yaml
+Type: System.Guid[]
+DefaultValue: ''
+SupportsWildcards: false
+Aliases: []
+ParameterSets:
+- Name: (All)
+  Position: 1
+  IsRequired: true
+  ValueFromPipeline: false
+  ValueFromPipelineByPropertyName: false
+  ValueFromRemainingArguments: false
+DontShow: false
+AcceptedValues: []
+HelpMessage: ''
+```
+
+### -DomainId
+
+The unique identifier of the Fabric domain to which the workspaces will be assigned.
+
+```yaml
+Type: System.Guid
+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
+
+- Requires `$FabricConfig` global configuration, including `BaseUrl` and `FabricHeaders`.
+- Calls `Confirm-TokenState` to ensure token validity before making the API request.
+
+Author: Tiago Balabuch
+
+## RELATED LINKS
+
+{{ Fill in the related links here }}
+