Conversation
| Thanks for your contribution! The pull request validation has started. Please revisit this comment for updated status. |
There was a problem hiding this comment.
Pull request overview
Updates repository help-generation tooling and regenerated markdown help files to align with the newer PlatyPS module/package naming and schema output.
Changes:
- Switched documentation and pipeline installation steps from
platyPStoMicrosoft.PowerShell.PlatyPS. - Regenerated many Az.Storage markdown help files with updated PlatyPS schema metadata/sections.
- Updated developer docs/static analysis docs to reference the new PlatyPS module name and links.
Reviewed changes
Copilot reviewed 57 out of 202 changed files in this pull request and generated 20 comments.
Show a summary per file
| File | Description |
|---|---|
| src/Storage/Storage.Management/help/Get-AzStorageFileServiceUsage.md | Regenerated cmdlet help with new PlatyPS front-matter/schema and parameter blocks. |
| src/Storage/Storage.Management/help/Get-AzStorageFileServiceProperty.md | Regenerated cmdlet help formatting/metadata for updated PlatyPS schema. |
| src/Storage/Storage.Management/help/Get-AzStorageFileCopyState.md | Regenerated cmdlet help; parameter metadata expanded and related links list reformatted. |
| src/Storage/Storage.Management/help/Get-AzStorageEncryptionScope.md | Regenerated cmdlet help; updated parameter metadata and common parameters section. |
| src/Storage/Storage.Management/help/Get-AzStorageContainerStoredAccessPolicy.md | Regenerated help; added parameter-set blocks and reformatted related links. |
| src/Storage/Storage.Management/help/Get-AzStorageCORSRule.md | Regenerated help; added additional syntax blocks and accepted values formatting. |
| src/Storage/Storage.Management/help/Get-AzStorageBlobServiceProperty.md | Regenerated help; added HelpUri/ms.date and expanded parameter details. |
| src/Storage/Storage.Management/help/Get-AzStorageBlobInventoryPolicy.md | Regenerated help; added metadata and expanded parameter YAML blocks. |
| src/Storage/Storage.Management/help/Get-AzStorageBlobByTag.md | Regenerated help; expanded parameter YAML blocks and added schema metadata. |
| src/Storage/Storage.Management/help/Get-AzStorageAccountNetworkRuleSet.md | Regenerated help; new metadata blocks and accepted values formatting. |
| src/Storage/Storage.Management/help/Get-AzStorageAccountNameAvailability.md | Regenerated help; added schema metadata and expanded parameter YAML blocks. |
| src/Storage/Storage.Management/help/Get-AzStorageAccountMigration.md | Regenerated help; added runtime parameters (Break/Proxy/Pipeline steps). |
| src/Storage/Storage.Management/help/Get-AzStorageAccountManagementPolicy.md | Regenerated help; updated metadata and expanded input/output sections. |
| src/Storage/Storage.Management/help/Get-AzStorageAccountKey.md | Regenerated help; front-matter expanded but content replaced with templates. |
| src/Storage/Storage.Management/help/Get-AzStorageAccount.md | Regenerated help; front-matter expanded but content replaced with templates. |
| src/Storage/Storage.Management/help/Get-AzRmStorageContainerImmutabilityPolicy.md | Regenerated help; updated metadata and expanded parameter definitions. |
| src/Storage/Storage.Management/help/Get-AzRmStorageContainer.md | Regenerated help; updated metadata and expanded parameter definitions. |
| src/Storage/Storage.Management/help/Get-AzDataLakeGen2Item.md | Regenerated help; updated metadata and expanded parameter YAML blocks. |
| src/Storage/Storage.Management/help/Get-AzDataLakeGen2DeletedItem.md | Regenerated help; updated metadata and expanded parameter YAML blocks. |
| src/Storage/Storage.Management/help/Get-AzDataLakeGen2ChildItem.md | Regenerated help; updated metadata and expanded parameter YAML blocks. |
| src/Storage/Storage.Management/help/Enable-AzStorageStaticWebsite.md | Regenerated help; added confirm/whatif parameter docs and metadata. |
| src/Storage/Storage.Management/help/Enable-AzStorageDeleteRetentionPolicy.md | Regenerated help; added confirm/whatif parameter docs and metadata. |
| src/Storage/Storage.Management/help/Enable-AzStorageContainerDeleteRetentionPolicy.md | Regenerated help; updated metadata and parameter block formatting. |
| src/Storage/Storage.Management/help/Enable-AzStorageBlobRestorePolicy.md | Regenerated help; updated metadata and parameter block formatting. |
| src/Storage/Storage.Management/help/Enable-AzStorageBlobLastAccessTimeTracking.md | Regenerated help; updated metadata and parameter block formatting. |
| src/Storage/Storage.Management/help/Enable-AzStorageBlobDeleteRetentionPolicy.md | Regenerated help; updated metadata and parameter block formatting. |
| src/Storage/Storage.Management/help/Disable-AzStorageStaticWebsite.md | Regenerated help; content replaced with templates and metadata expanded. |
| src/Storage/Storage.Management/help/Disable-AzStorageDeleteRetentionPolicy.md | Regenerated help; updated metadata and parameter block formatting. |
| src/Storage/Storage.Management/help/Disable-AzStorageContainerDeleteRetentionPolicy.md | Regenerated help; updated metadata and parameter block formatting. |
| src/Storage/Storage.Management/help/Disable-AzStorageBlobRestorePolicy.md | Regenerated help; updated metadata and parameter block formatting. |
| src/Storage/Storage.Management/help/Disable-AzStorageBlobLastAccessTimeTracking.md | Regenerated help; updated metadata and parameter block formatting. |
| src/Storage/Storage.Management/help/Disable-AzStorageBlobDeleteRetentionPolicy.md | Regenerated help; updated metadata and parameter block formatting. |
| documentation/tooling/static-analysis.md | Updated references/links for PlatyPS schema and module name. |
| documentation/development-docs/sdkbased-vs-autogen.md | Updated doc generation tool reference to Microsoft.PowerShell.PlatyPS. |
| documentation/development-docs/help-generation.md | Updated help-generation instructions and cmdlet names referenced. |
| documentation/development-docs/azure-powershell-developer-guide.md | Updated prerequisites/help generation section to new module name. |
| .github/copilot-instructions.md | Updated repo setup instructions to install Microsoft.PowerShell.PlatyPS. |
| .azure-pipelines/util/analyze-steps.yml | Updated pipeline dependency install to Microsoft.PowerShell.PlatyPS. |
| .azure-pipelines/security-tools.yml | Updated pipeline step name/script to install Microsoft.PowerShell.PlatyPS. |
You can also share your feedback on Copilot code review. Take the survey.
| ```powershell | ||
| $PathToHelpFolder = "../../help" # Full path to help folder containing markdown files to be generated (e.g., src/Accounts/Accounts/help) | ||
| New-MarkdownHelp -Module {{moduleName}} -OutputFolder $PathToHelpFolder -AlphabeticParamsOrder -UseFullTypeName -WithModulePage | ||
| New-MarkdownCommandHelp -ModuleInfo (Get-Module {{moduleName}}) -OutputFolder $PathToHelpFolder -WithModulePage |
| # Update individual command help markdown files | ||
| Update-MarkdownCommandHelp -Path "$PathToHelpFolder/*-*.md" | ||
|
|
||
| # Refresh the module page with updated command list | ||
| $cmdHelp = Import-MarkdownCommandHelp -Path "$PathToHelpFolder/*-*.md" | ||
| $moduleFile = Get-ChildItem -Path $PathToHelpFolder -Filter "Az.*.md" | Where-Object { $_.Name -notlike "*-*" } | Select-Object -First 1 | ||
| if ($moduleFile) { Update-MarkdownModuleFile -Path $moduleFile.FullName -CommandHelp $cmdHelp } |
| $cmdHelp = Import-MarkdownCommandHelp -Path "$PathToHelpFolder/*-*.md" | ||
| Export-MamlCommandHelp -CommandHelp $cmdHelp -OutputFolder $PathToOutputFolder |
|
|
||
| # Save the help locally | ||
| $help = Get-HelpPreview -Path $PathToMAML | ||
| $help = Show-HelpPreview -Path $PathToMAML |
| --- | ||
| document type: cmdlet | ||
| external help file: Microsoft.Azure.PowerShell.Cmdlets.Storage.Management.dll-Help.xml | ||
| HelpUri: '' |
| --- | ||
| document type: cmdlet | ||
| external help file: Microsoft.Azure.PowerShell.Cmdlets.Storage.Management.dll-Help.xml | ||
| HelpUri: https://learn.microsoft.com/powershell/module/Az.storage/get-Azstorageaccountmanagementpolicy |
|
|
||
| Indicates that this cmdlet waits for the copy to finish. | ||
| If you do not specify this parameter, this cmdlet returns a result immediately. | ||
| Indicates whether or not to wait util the copying finished. |
|
|
||
| Filters the result set to only include blobs whose tags match the specified expression. | ||
| See details in https://learn.microsoft.com/en-us/rest/api/storageservices/find-blobs-by-tags#remarks. | ||
| Filters the result set to only include blobs whose tags match the specified expression.See details in https://learn.microsoft.com/en-us/rest/api/storageservices/find-blobs-by-tags#remarks. |
| The path in the specified Filesystem that should be retrieved. | ||
| Can be a file or directory In the format 'directory/file.txt' or 'directory1/directory2/'. | ||
| Not specify this parameter to get the root directory of the Filesystem. | ||
| The path in the specified FileSystem that should be retrieved. Can be a file or directory In the format 'directory/file.txt' or 'directory1/directory2/'. Skip set this parameter to get the root directory of the Filesystem. |
| ### System.Management.Automation.PSObject | ||
|
|
||
| ## RELATED LINKS | ||
| {{ Fill in the Description }} |
vidai-msft
force-pushed
the
vidai/upgrade-platyps
branch
from
fabc750 to
e982623
Compare
vidai-msft
force-pushed
the
vidai/upgrade-platyps
branch
from
e982623 to
a4974b5
Compare
vidai-msft
force-pushed
the
vidai/upgrade-platyps
branch
from
a4974b5 to
46dc3a2
Compare
vidai-msft
force-pushed
the
vidai/upgrade-platyps
branch
from
46dc3a2 to
5b74631
Compare
| @@ -1,43 +1,56 @@ | |||
| --- | |||
| --- | |||
There was a problem hiding this comment.
The YAML front matter opening delimiter appears to include a UTF-8 BOM character (shown as an invisible/special character before ---). This can break tools that expect the file to start with --- as the first bytes (including YAML front matter detection). Please re-save regenerated help markdown without BOM so the file begins with plain ---.
| --- | |
| --- |
| ## SYNOPSIS | ||
| Gets the access keys for an Azure Storage account. | ||
|
|
||
| {{ Fill in the Synopsis }} |
There was a problem hiding this comment.
This regeneration replaces previously complete help content (synopsis/description/examples/related links) with placeholders, which is a functional regression for end-user Get-Help output and likely to fail documentation quality gates. Please preserve the existing human-authored help text when updating to the new PlatyPS schema (or restore the previous content and only apply schema/formatting changes).
| ## ALIASES | ||
|
|
||
| ### Example 2: Get a specific access key for a Storage account | ||
| <!-- Skip: Output cannot be splitted from code --> | ||
| This cmdlet has the following aliases, | ||
| {{Insert list of aliases}} | ||
|
|
||
| ## DESCRIPTION | ||
|
|
||
| ``` | ||
| This command gets a specific key for a Storage account. | ||
| (Get-AzStorageAccountKey -ResourceGroupName "RG01" -Name "mystorageaccount")| Where-Object {$_.KeyName -eq "key1"} | ||
|
|
||
| KeyName Value Permissions CreationTime | ||
| ------- ----- ----------- ------------ | ||
| key1 <KeyValue> Full | ||
|
|
||
| This command gets a specific key value for a Storage account. | ||
| (Get-AzStorageAccountKey -ResourceGroupName "RG01" -Name "mystorageaccount")[0].Value | ||
| {{ Fill in the Description }} |
There was a problem hiding this comment.
This regeneration replaces previously complete help content (synopsis/description/examples/related links) with placeholders, which is a functional regression for end-user Get-Help output and likely to fail documentation quality gates. Please preserve the existing human-authored help text when updating to the new PlatyPS schema (or restore the previous content and only apply schema/formatting changes).
| ### Example 1 | ||
|
|
||
| This command gets the keys for the specified Azure Storage account. | ||
| {{ Add example description here }} |
There was a problem hiding this comment.
This regeneration replaces previously complete help content (synopsis/description/examples/related links) with placeholders, which is a functional regression for end-user Get-Help output and likely to fail documentation quality gates. Please preserve the existing human-authored help text when updating to the new PlatyPS schema (or restore the previous content and only apply schema/formatting changes).
|
|
||
| ## NOTES | ||
|
|
||
| {{ Fill in the Notes }} |
There was a problem hiding this comment.
This regeneration replaces previously complete help content (synopsis/description/examples/related links) with placeholders, which is a functional regression for end-user Get-Help output and likely to fail documentation quality gates. Please preserve the existing human-authored help text when updating to the new PlatyPS schema (or restore the previous content and only apply schema/formatting changes).
| ### Microsoft.Azure.Storage.Blob.SharedAccessBlobPolicy | ||
|
|
||
| ## NOTES | ||
| ### System.Management.Automation.PSObject | ||
|
|
||
| ## RELATED LINKS | ||
| {{ Fill in the Description }} | ||
|
|
||
| [New-AzStorageContainerStoredAccessPolicy](./New-AzStorageContainerStoredAccessPolicy.md) | ||
| ## NOTES | ||
|
|
||
| [Remove-AzStorageContainerStoredAccessPolicy](./Remove-AzStorageContainerStoredAccessPolicy.md) | ||
| ## RELATED LINKS |
There was a problem hiding this comment.
The INPUTS/NOTES section structure appears corrupted: a ### System.Management.Automation.PSObject entry and {{ Fill in the Description }} placeholder are inserted before ## NOTES, which is not valid/expected help markdown structure. This may break PlatyPS schema validation and produces confusing help. Please restore a valid ## INPUTS section (with optional descriptions) and ensure placeholders are not emitted.
| ```powershell | ||
| $PathToHelpFolder = "../../help" # Full path to help folder containing markdown files to be generated (e.g., src/Accounts/Accounts/help) | ||
| New-MarkdownHelp -Module {{moduleName}} -OutputFolder $PathToHelpFolder -AlphabeticParamsOrder -UseFullTypeName -WithModulePage | ||
| New-MarkdownCommandHelp -ModuleInfo (Get-Module {{moduleName}}) -OutputFolder $PathToHelpFolder -WithModulePage |
There was a problem hiding this comment.
The updated doc switches to newer PlatyPS cmdlets (e.g., New-MarkdownCommandHelp, Update-MarkdownModuleFile, Show-HelpPreview). To avoid developer confusion and broken instructions, please (1) ensure these cmdlets exist in the minimum version you require (the PR title mentions 1.0.1), and (2) consider adding a short note on the exact required Microsoft.PowerShell.PlatyPS version and/or links to the upstream command docs for these cmdlets.
|
|
||
| If you would like to update the inputs/outputs for a markdown file, please run this cmdlet with the -UpdateInputOutput parameter. Keep in mind that this will overwrite any customized descriptions of inputs and outputs, so you will need to add these descriptions back if still relevant. | ||
| # Update individual command help markdown files | ||
| Update-MarkdownCommandHelp -Path "$PathToHelpFolder/*-*.md" |
There was a problem hiding this comment.
The updated doc switches to newer PlatyPS cmdlets (e.g., New-MarkdownCommandHelp, Update-MarkdownModuleFile, Show-HelpPreview). To avoid developer confusion and broken instructions, please (1) ensure these cmdlets exist in the minimum version you require (the PR title mentions 1.0.1), and (2) consider adding a short note on the exact required Microsoft.PowerShell.PlatyPS version and/or links to the upstream command docs for these cmdlets.
| # Refresh the module page with updated command list | ||
| $cmdHelp = Import-MarkdownCommandHelp -Path "$PathToHelpFolder/*-*.md" | ||
| $moduleFile = Get-ChildItem -Path $PathToHelpFolder -Filter "Az.*.md" | Where-Object { $_.Name -notlike "*-*" } | Select-Object -First 1 | ||
| if ($moduleFile) { Update-MarkdownModuleFile -Path $moduleFile.FullName -CommandHelp $cmdHelp } |
There was a problem hiding this comment.
The updated doc switches to newer PlatyPS cmdlets (e.g., New-MarkdownCommandHelp, Update-MarkdownModuleFile, Show-HelpPreview). To avoid developer confusion and broken instructions, please (1) ensure these cmdlets exist in the minimum version you require (the PR title mentions 1.0.1), and (2) consider adding a short note on the exact required Microsoft.PowerShell.PlatyPS version and/or links to the upstream command docs for these cmdlets.
|
|
||
| # Save the help locally | ||
| $help = Get-HelpPreview -Path $PathToMAML | ||
| $help = Show-HelpPreview -Path $PathToMAML |
There was a problem hiding this comment.
The updated doc switches to newer PlatyPS cmdlets (e.g., New-MarkdownCommandHelp, Update-MarkdownModuleFile, Show-HelpPreview). To avoid developer confusion and broken instructions, please (1) ensure these cmdlets exist in the minimum version you require (the PR title mentions 1.0.1), and (2) consider adding a short note on the exact required Microsoft.PowerShell.PlatyPS version and/or links to the upstream command docs for these cmdlets.
Description
Mandatory Checklist
Please choose the target release of Azure PowerShell. (⚠️ Target release is a different concept from API readiness. Please click below links for details.)
Check this box to confirm: I have read the Submitting Changes section of
CONTRIBUTING.mdand reviewed the following information:ChangeLog.mdfile(s) appropriatelysrc/{{SERVICE}}/{{SERVICE}}/ChangeLog.md.## Upcoming Releaseheader in the past tense.ChangeLog.mdif no new release is required, such as fixing test case only.