Skip to content

Commit e5f4a0a

Browse files
NowinskiKNowinskiK
authored
Merge pull request #150 from Gijsreyn/microsoft-powershell-platyps
Add Microsoft.PowerShell.PlatyPS documentation
2 parents 1aacaae + 154ae13 commit e5f4a0a

File tree

619 files changed

+37025
-28765
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

619 files changed

+37025
-28765
lines changed

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

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
param
2+
(
3+
[Parameter()]
4+
[System.IO.DirectoryInfo]
5+
$ProjectPath = (property ProjectPath $BuildRoot),
6+
7+
[Parameter()]
8+
[System.String]
9+
$ProjectName = (property ProjectName ''),
10+
11+
[Parameter()]
12+
[System.String]
13+
$SourcePath = (property SourcePath ''),
14+
15+
[Parameter()]
16+
[System.String]
17+
$HelpSourceFolder = (property HelpSourceFolder 'docs'),
18+
19+
[Parameter()]
20+
[System.String]
21+
$OutputDirectory = (property OutputDirectory 'output'),
22+
23+
[Parameter()]
24+
[System.String]
25+
$BuiltModuleSubdirectory = (property BuiltModuleSubdirectory ''),
26+
27+
[Parameter()]
28+
[System.Management.Automation.SwitchParameter]
29+
$VersionedOutputDirectory = (property VersionedOutputDirectory $true),
30+
31+
[Parameter()]
32+
[System.String]
33+
$HelpOutputFolder = (property HelpOutputFolder 'help'),
34+
35+
[Parameter()]
36+
[cultureInfo]
37+
$HelpCultureInfo = 'en-US',
38+
39+
[Parameter()]
40+
[System.Management.Automation.SwitchParameter]
41+
$CopyHelpMamlToBuiltModuleBase = (property CopyHelpMamlToBuiltModuleBase $true),
42+
43+
# Build Configuration object
44+
[Parameter()]
45+
[System.Collections.Hashtable]
46+
$BuildInfo = (property BuildInfo @{ })
47+
)
48+
49+
function Get-GenerateHelpPSVariables
50+
{
51+
param ()
52+
53+
$script:PesterOutputFolder = Get-SamplerAbsolutePath -Path $PesterOutputFolder -RelativeTo $OutputDirectory
54+
55+
"`tPester Output Folder = '$PesterOutputFolder"
56+
57+
$script:HelpSourceFolder = Get-SamplerAbsolutePath -Path $HelpSourceFolder -RelativeTo $ProjectPath
58+
"`tHelp Source Folder = '$HelpSourceFolder'"
59+
60+
$script:HelpOutputFolder = Get-SamplerAbsolutePath -Path $HelpOutputFolder -RelativeTo $OutputDirectory
61+
"`tHelp output Folder = '$HelpOutputFolder'"
62+
63+
if ($ModuleVersion)
64+
{
65+
$script:HelpOutputVersionFolder = Get-SamplerAbsolutePath -Path $ModuleVersion -RelativeTo $HelpOutputFolder
66+
}
67+
68+
"`tHelp output Version Folder = '$HelpOutputVersionFolder'"
69+
70+
$script:HelpOutputCultureFolder = Get-SamplerAbsolutePath -Path $HelpCultureInfo -RelativeTo $HelpOutputVersionFolder
71+
"`tHelp output Culture path = '$HelpOutputCultureFolder'"
72+
73+
$script:DocOutputFolder = Get-SamplerAbsolutePath -Path 'docs' -RelativeTo $OutputDirectory
74+
"`tDocs output folder path = '$DocOutputFolder'"
75+
}
76+
77+
# Synopsis: Produces markdown help files from the built module.
78+
task Generate_help_from_built_module {
79+
. Set-SamplerTaskVariable
80+
81+
Get-GenerateHelpPSVariables
82+
83+
$generateHelpCommands = @"
84+
`$env:PSModulePath = '$Env:PSModulePath'
85+
`$targetModule = Import-Module -Name '$ProjectName' -ErrorAction Stop -Passthru
86+
87+
`$helpDestination = Join-Path '$HelpSourceFolder' -ChildPath '$HelpCultureInfo'
88+
89+
if (!(Test-Path -Path `$helpDestination)) {
90+
New-Item -Path `$helpDestination -ItemType Directory -Force -ErrorAction Ignore | Out-Null
91+
}
92+
93+
`$docOutputFolder = Join-Path '$DocOutputFolder' -ChildPath '$ProjectName'
94+
95+
`$commandsArray = @()
96+
foreach (`$publicFunction in `$targetModule.ExportedFunctions.Keys) {
97+
`$command = Get-Command -Name `$publicFunction -Module `$targetModule
98+
99+
`$newMarkdownCommandHelpParams = @{
100+
CommandInfo = `$command
101+
OutputFolder = '$DocOutputFolder'
102+
HelpVersion = `$targetModule.Version
103+
Locale = '$HelpCultureInfo'
104+
Encoding = 'utf8'
105+
Force = `$true
106+
}
107+
`$Output = New-MarkdownCommandHelp @newMarkdownCommandHelpParams
108+
109+
`$helpCommand = Import-MarkdownCommandHelp -Path `$Output -ErrorAction Ignore
110+
111+
# Add the command to the array
112+
`$commandsArray += `$helpCommand
113+
114+
`$alias = Get-Alias -Definition `$command.Name -ErrorAction Ignore
115+
116+
if (`$alias) {
117+
`$helpCommand.Aliases = @(`$alias.Name)
118+
} else {
119+
`$helpCommand.Aliases = @()
120+
}
121+
122+
`$helpCommand | Export-MarkdownCommandHelp -OutputFolder '$DocOutputFolder' -Force
123+
124+
Copy-Item -Path `$Output -Destination `$helpDestination -Force
125+
}
126+
127+
`$newMarkdownModuleFileParams = @{
128+
CommandHelp = `$commandsArray
129+
OutputFolder = '$DocOutputFolder'
130+
Force = `$true
131+
}
132+
`$markdownFile = New-MarkdownModuleFile @newMarkdownModuleFileParams
133+
134+
if (`$markdownFile) {
135+
Copy-Item -Path `$markdownFile -Destination `$helpDestination -Force
136+
}
137+
138+
"@
139+
Write-Build -Color DarkGray -Text "$generateHelpCommands"
140+
$sb = [ScriptBlock]::create($generateHelpCommands)
141+
142+
$pwshPath = (Get-Process -Id $PID).Path
143+
&$pwshPath -Command $sb -ExecutionPolicy 'ByPass'
144+
}

‎CHANGELOG.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
2424
- `Start-FabricDeploymentPipelineStage`
2525
- Added private function `Get-FabricContinuationToken` to facilitate pagination
2626
- `Invoke-FabricRestMethod` handles throttling (error 429) by pausing and repeating the request (#88)
27+
- New build automation task added `Generate_help_from_built_module`
2728

2829
### Changed
2930

@@ -40,6 +41,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
4041
- All Deployment Pipeline functions raise an error when an exception is caught. Used splatting for params.
4142
- Refactored SQL Database functions to use enhanced capability in `Invoke-FabricRestMethod`. Used splatting for params.
4243
- `Write-Message` uses PSFramework function for logging, which logs function name (#84)
44+
- Changed the `documentation` folder to `docs/<locale>`
45+
- Code-fenced blocks included in function examples
4346

4447
### Fixed
4548

‎CONTRIBUTING.md

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ The workflow for using this and developing the code is shown below.
3636

3737
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.
3838

39-
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.
39+
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.
4040

4141
```PowerShell
4242
.\build.ps1 -ResolveDependency -Tasks noop -UsePSResourceGet
@@ -105,7 +105,14 @@ You should also resolve all dependencies before you start developing. This will
105105
### Fixed
106106
- Fixed issue with `New-FabricDataPipeline` not working correctly.
107107
```
108-
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.
108+
109+
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:
110+
111+
```powershell
112+
./build.ps1 -Tasks Generate_help_from_built_module
113+
```
114+
115+
11. When the process finishes, the documentation should be updated. Now push your branch to GitHub and create a PR against the repo.
109116

110117
## Thanks!
111118

‎RequiredModules.psd1

Lines changed: 19 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -11,17 +11,23 @@
1111
# Repository = 'PSGallery'
1212
# }
1313
#}
14-
Assert = "0.9.6"
15-
InvokeBuild = 'latest'
16-
PSScriptAnalyzer = '1.19.1'
17-
Pester = 'latest'
18-
ModuleBuilder = 'latest'
19-
ChangelogManagement = 'latest'
20-
Sampler = 'latest'
21-
'Sampler.GitHubTasks' = 'latest'
22-
MarkdownLinkCheck = 'latest'
23-
PSFramework = 'latest'
24-
'Az.Accounts' = '5.0.0'
25-
'Az.Resources' = '6.15.1'
26-
'MicrosoftPowerBIMgmt' = '1.2.1111'
14+
Assert = "0.9.6"
15+
InvokeBuild = 'latest'
16+
PSScriptAnalyzer = '1.19.1'
17+
Pester = 'latest'
18+
ModuleBuilder = 'latest'
19+
ChangelogManagement = 'latest'
20+
Sampler = 'latest'
21+
'Sampler.GitHubTasks' = 'latest'
22+
MarkdownLinkCheck = 'latest'
23+
PSFramework = 'latest'
24+
'Az.Accounts' = '5.0.0'
25+
'Az.Resources' = '6.15.1'
26+
'MicrosoftPowerBIMgmt' = '1.2.1111'
27+
'Microsoft.PowerShell.PlatyPS' = @{
28+
Version = '1.0.0-rc1'
29+
Parameters = @{
30+
AllowPrerelease = $true
31+
} # TODO: Simply remove after GA
32+
}
2733
}

‎build.yaml

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,6 @@ BuildWorkflow:
5252
- Build_NestedModules_ModuleBuilder
5353
- Create_changelog_release_output
5454

55-
5655
pack:
5756
- build
5857
- package_module_nupkg

‎docs/en-US/Add-FabricDomainWorkspaceAssignmentByCapacity.md

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
---
2+
document type: cmdlet
3+
external help file: FabricTools-Help.xml
4+
HelpUri: ''
5+
Locale: en-US
6+
Module Name: FabricTools
7+
ms.date: 07/18/2025
8+
PlatyPS schema version: 2024-05-01
9+
title: Add-FabricDomainWorkspaceAssignmentByCapacity
10+
---
11+
12+
# Add-FabricDomainWorkspaceAssignmentByCapacity
13+
14+
## SYNOPSIS
15+
16+
Assigns workspaces to a Fabric domain based on specified capacities.
17+
18+
## SYNTAX
19+
20+
### __AllParameterSets
21+
22+
```
23+
Add-FabricDomainWorkspaceAssignmentByCapacity [-DomainId] <guid> [-CapacitiesIds] <guid[]>
24+
[<CommonParameters>]
25+
```
26+
27+
## ALIASES
28+
29+
Assign-FabricDomainWorkspaceByCapacity
30+
31+
## DESCRIPTION
32+
33+
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.
34+
35+
## EXAMPLES
36+
37+
### EXAMPLE 1
38+
39+
Assigns workspaces to the domain with ID "12345" based on the specified capacities.
40+
41+
```powershell
42+
Add-FabricDomainWorkspaceAssignmentByCapacity -DomainId "12345" -CapacitiesIds @("capacity1", "capacity2")
43+
```
44+
45+
## PARAMETERS
46+
47+
### -CapacitiesIds
48+
49+
An array of capacity IDs used to assign workspaces to the domain.
50+
51+
```yaml
52+
Type: System.Guid[]
53+
DefaultValue: ''
54+
SupportsWildcards: false
55+
Aliases: []
56+
ParameterSets:
57+
- Name: (All)
58+
Position: 1
59+
IsRequired: true
60+
ValueFromPipeline: false
61+
ValueFromPipelineByPropertyName: false
62+
ValueFromRemainingArguments: false
63+
DontShow: false
64+
AcceptedValues: []
65+
HelpMessage: ''
66+
```
67+
68+
### -DomainId
69+
70+
The unique identifier of the Fabric domain to which the workspaces will be assigned.
71+
72+
```yaml
73+
Type: System.Guid
74+
DefaultValue: ''
75+
SupportsWildcards: false
76+
Aliases: []
77+
ParameterSets:
78+
- Name: (All)
79+
Position: 0
80+
IsRequired: true
81+
ValueFromPipeline: false
82+
ValueFromPipelineByPropertyName: false
83+
ValueFromRemainingArguments: false
84+
DontShow: false
85+
AcceptedValues: []
86+
HelpMessage: ''
87+
```
88+
89+
### CommonParameters
90+
91+
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable,
92+
-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable,
93+
-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see
94+
[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).
95+
96+
## INPUTS
97+
98+
## OUTPUTS
99+
100+
## NOTES
101+
102+
- Requires `$FabricConfig` global configuration, including `BaseUrl` and `FabricHeaders`.
103+
- Calls `Confirm-TokenState` to ensure token validity before making the API request.
104+
105+
Author: Tiago Balabuch
106+
107+
## RELATED LINKS
108+
109+
{{ Fill in the related links here }}
110+

0 commit comments

Comments
 (0)