From 55e7bd7048852a22dd6ba88af353719a0e400fe6 Mon Sep 17 00:00:00 2001 From: Gabriel Ngandu-Biseba Date: Thu, 17 Apr 2025 10:39:23 +0200 Subject: [PATCH 1/6] Add primitive support for custom types in outputs --- src/PSDocs.Azure/docs/Azure.Template.Doc.ps1 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/PSDocs.Azure/docs/Azure.Template.Doc.ps1 b/src/PSDocs.Azure/docs/Azure.Template.Doc.ps1 index b449c2f3..dd8f7d36 100644 --- a/src/PSDocs.Azure/docs/Azure.Template.Doc.ps1 +++ b/src/PSDocs.Azure/docs/Azure.Template.Doc.ps1 @@ -218,7 +218,7 @@ function global:GetTemplateOutput { foreach ($property in $InputObject.outputs.PSObject.Properties) { $output = [PSCustomObject]@{ Name = $property.Name - Type = $property.Value.type + Type = If ($null -eq $property.Value.'$ref') {$property.Value.type} Else {$property.Value.'$ref'} Description = '' } if ([bool]$property.Value.PSObject.Properties['metadata'] -and [bool]$property.Value.metadata.PSObject.Properties['description']) { From 6aa512ba7c6c4ef423d66875b0f6c947d8b74c29 Mon Sep 17 00:00:00 2001 From: Gabriel Ngandu-Biseba Date: Thu, 17 Apr 2025 11:33:02 +0200 Subject: [PATCH 2/6] Remove ternary if which is only supported in powershell 7 and later --- src/PSDocs.Azure/docs/Azure.Template.Doc.ps1 | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/src/PSDocs.Azure/docs/Azure.Template.Doc.ps1 b/src/PSDocs.Azure/docs/Azure.Template.Doc.ps1 index dd8f7d36..7ca5ea9b 100644 --- a/src/PSDocs.Azure/docs/Azure.Template.Doc.ps1 +++ b/src/PSDocs.Azure/docs/Azure.Template.Doc.ps1 @@ -216,9 +216,16 @@ function global:GetTemplateOutput { ) process { foreach ($property in $InputObject.outputs.PSObject.Properties) { + $type = $null; + if($null -eq $property.Value.'$ref') { + $type = $property.Value.type; + } + else { + $type = $property.Value.'$ref'; + } $output = [PSCustomObject]@{ Name = $property.Name - Type = If ($null -eq $property.Value.'$ref') {$property.Value.type} Else {$property.Value.'$ref'} + Type = $type Description = '' } if ([bool]$property.Value.PSObject.Properties['metadata'] -and [bool]$property.Value.metadata.PSObject.Properties['description']) { From 8808494745e537b9acb223453e5a6cdbba988985 Mon Sep 17 00:00:00 2001 From: Gabriel Ngandu-Biseba Date: Tue, 22 Apr 2025 10:17:11 +0200 Subject: [PATCH 3/6] Add support for user-defined types --- src/PSDocs.Azure/docs/Azure.Template.Doc.ps1 | 97 ++++++++++++++++++-- src/PSDocs.Azure/en/PSDocs-strings.psd1 | 10 +- 2 files changed, 98 insertions(+), 9 deletions(-) diff --git a/src/PSDocs.Azure/docs/Azure.Template.Doc.ps1 b/src/PSDocs.Azure/docs/Azure.Template.Doc.ps1 index 7ca5ea9b..f7da2d40 100644 --- a/src/PSDocs.Azure/docs/Azure.Template.Doc.ps1 +++ b/src/PSDocs.Azure/docs/Azure.Template.Doc.ps1 @@ -216,26 +216,63 @@ function global:GetTemplateOutput { ) process { foreach ($property in $InputObject.outputs.PSObject.Properties) { - $type = $null; - if($null -eq $property.Value.'$ref') { - $type = $property.Value.type; - } - else { - $type = $property.Value.'$ref'; - } $output = [PSCustomObject]@{ Name = $property.Name - Type = $type + Type = If ($null -eq $property.Value.'$ref') {$property.Value.type} Else {GetDefinitionReferenceMarkdownLink $property.Value.'$ref'} Description = '' } if ([bool]$property.Value.PSObject.Properties['metadata'] -and [bool]$property.Value.metadata.PSObject.Properties['description']) { + $output.Description = $property.Value.metadata.description + } $output; } } } +# A function to import user-defined types +function global:GetTemplateDefinition { + [CmdletBinding()] + param ( + [Parameter(Mandatory = $True, ValueFromPipeline = $True)] + [PSObject]$InputObject + ) + process { + foreach ($property in $InputObject.definitions.PSObject.Properties) { + $definition = [PSCustomObject]@{ + Name = $property.Name + Properties = $property.PSObject.Properties + Description = '' + AdditionalProperties = $false + Discriminator = $null + } + if ([bool]$property.Value.PSObject.Properties['metadata'] -and [bool]$property.Value.metadata.PSObject.Properties['description']) { + $definition.Description = $property.Value.metadata.description + } + if($null -ne $property.Value.PSObject.Properties['additionalProperties'] -and $property.Value.PSObject.Properties['additionalProperties'] -ne $false) { + $definition.AdditionalProperties = $property.Value.additionalProperties; + } + if($null -ne $property.Value.PSObject.Properties['discriminator']) { + Write-Warning "Discriminator found" + $definition.Discriminator = $property.Value.discriminator; + } + $definition; + } + } +} + +function global:GetDefinitionReferenceMarkdownLink { + [CmdletBinding()] + param ( + [Parameter(Mandatory = $True)] + [String]$DefinitionPath + ) + process { + return "[$($DefinitionPath)](#$($DefinitionPath.Split('/')[-1].ToLower().Replace(' ', '-')))" + } +} + # Synopsis: A definition to generate markdown for an ARM template Document 'README' -With 'Azure.TemplateSchema' { @@ -257,6 +294,8 @@ Document 'README' -With 'Azure.TemplateSchema' { $parameters = $template | GetTemplateParameter; $metadata = $template | GetTemplateMetadata -Path $templatePath; $outputs = $template | GetTemplateOutput; + $definitions = $template | GetTemplateDefinition; + # Set document title if ($Null -ne $metadata -and $metadata.ContainsKey('name')) { @@ -305,6 +344,48 @@ Document 'README' -With 'Azure.TemplateSchema' { $metadata.details } } + Section $LocalizedData.Definitions { + foreach($definition in $definitions) { + Section $definition.Name { + + $definition.Description; + + $definitionProperties = $definition.Properties.Value.Properties; + if($null -ne $definitionProperties -and $definitionProperties.Count -gt 0) { + $definitionProperties.PSObject.Properties | Table -Property @{ Name = $LocalizedData.PropertyName; Expression = { $_.Name }}, + @{ Name = $LocalizedData.Type; Expression = { + If($null -eq $_.Value.'$ref') { $_.Value.Type } Else { GetDefinitionReferenceMarkdownLink $_.Value.'$ref' } + }}, + @{ Name = $LocalizedData.Nullable; Expression = { If($null -ne $_.Value.nullable) { $_.Value.nullable } Else { 'False' }}}, + @{ Name = $LocalizedData.Description; Expression = { If($null -ne $_.Value.Metadata.Description) { $_.Value.Metadata.Description } Else { '' }}}, + @{ Name= $LocalizedData.AllowedValues; Expression = { + If($null -eq $_.Value.allowedValues) { 'Any' } Else { + $_.Value.allowedValues -join ' | ' # | = Pipe symbol = | + } + }} + } + + if ($null -ne $definition.AdditionalProperties -and $definition.AdditionalProperties -ne $false) { + "**$($LocalizedData.AdditionalProperties)**" + $(global:GetDefinitionReferenceMarkdownLink $definition.AdditionalProperties.'$ref') + } + + if($null -ne $definition.Discriminator) { + Section $LocalizedData.UnionTypes { + "**$($LocalizedData.DiscriminatorDescription)**" + $definition.Discriminator.propertyName | Code 'text' + + if($null -ne $definition.Discriminator.mapping) { + "**$($LocalizedData.Mapping)**" + $definition.Discriminator.mapping.PSObject.Properties | Table -Property @{ Name = $LocalizedData.Type; Expression = { $_.Name }}, + @{ Name = $LocalizedData.Definition; Expression = { GetDefinitionReferenceMarkdownLink $_.Value.'$ref' }} + } + + } + } + } + } + } # Add table and detail for each parameter Section $LocalizedData.Parameters { diff --git a/src/PSDocs.Azure/en/PSDocs-strings.psd1 b/src/PSDocs.Azure/en/PSDocs-strings.psd1 index 2a15d023..f7365f84 100644 --- a/src/PSDocs.Azure/en/PSDocs-strings.psd1 +++ b/src/PSDocs.Azure/en/PSDocs-strings.psd1 @@ -3,13 +3,20 @@ @{ Parameters = 'Parameters' + Definitions = 'User-defined types definitions' Snippets = 'Snippets' Outputs = 'Outputs' DefaultValue = 'Default value' AllowedValues = 'Allowed values' + AdditionalProperties = 'Additional properties' + PropertyName = 'Property name' ParameterName = 'Parameter name' Description = 'Description' - Type = 'Type' + Type = 'Type', + Definition = 'Definition' + UnionTypes = 'Union types' + DiscriminatorDescription = 'Property used to discriminate between types' + Mapping = 'Mapping' Name = 'Name' DefaultTitle = 'Azure template' ParameterFile = 'Parameter file' @@ -21,4 +28,5 @@ MaxValue = 'Maximum value' MinLength = 'Minimum length' MaxLength = 'Maximum length' + Nullable = 'Nullable' } From aad25f1c9022c199dd0408989579baf7b8d051bc Mon Sep 17 00:00:00 2001 From: Gabriel Ngandu-Biseba Date: Tue, 22 Apr 2025 10:22:27 +0200 Subject: [PATCH 4/6] Remove unexpected comma in psd1 file --- src/PSDocs.Azure/en/PSDocs-strings.psd1 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/PSDocs.Azure/en/PSDocs-strings.psd1 b/src/PSDocs.Azure/en/PSDocs-strings.psd1 index f7365f84..52b6a977 100644 --- a/src/PSDocs.Azure/en/PSDocs-strings.psd1 +++ b/src/PSDocs.Azure/en/PSDocs-strings.psd1 @@ -12,7 +12,7 @@ PropertyName = 'Property name' ParameterName = 'Parameter name' Description = 'Description' - Type = 'Type', + Type = 'Type' Definition = 'Definition' UnionTypes = 'Union types' DiscriminatorDescription = 'Property used to discriminate between types' From 81c55542ff05ff14edaa4f6a6f31c068bcf07370 Mon Sep 17 00:00:00 2001 From: Gabriel Ngandu-Biseba Date: Tue, 22 Apr 2025 10:35:40 +0200 Subject: [PATCH 5/6] Remove debugging 'Write-Warning' --- src/PSDocs.Azure/docs/Azure.Template.Doc.ps1 | 1 - 1 file changed, 1 deletion(-) diff --git a/src/PSDocs.Azure/docs/Azure.Template.Doc.ps1 b/src/PSDocs.Azure/docs/Azure.Template.Doc.ps1 index f7da2d40..814297ce 100644 --- a/src/PSDocs.Azure/docs/Azure.Template.Doc.ps1 +++ b/src/PSDocs.Azure/docs/Azure.Template.Doc.ps1 @@ -254,7 +254,6 @@ function global:GetTemplateDefinition { $definition.AdditionalProperties = $property.Value.additionalProperties; } if($null -ne $property.Value.PSObject.Properties['discriminator']) { - Write-Warning "Discriminator found" $definition.Discriminator = $property.Value.discriminator; } $definition; From 61a52ad6e2da73c6287fd35a9df46a808ef021a6 Mon Sep 17 00:00:00 2001 From: Gabriel Ngandu-Biseba Date: Tue, 22 Apr 2025 10:39:16 +0200 Subject: [PATCH 6/6] Add missed null check and ternary if on additional properties as it can also be a built-in type --- src/PSDocs.Azure/docs/Azure.Template.Doc.ps1 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/PSDocs.Azure/docs/Azure.Template.Doc.ps1 b/src/PSDocs.Azure/docs/Azure.Template.Doc.ps1 index 814297ce..2ef22e9f 100644 --- a/src/PSDocs.Azure/docs/Azure.Template.Doc.ps1 +++ b/src/PSDocs.Azure/docs/Azure.Template.Doc.ps1 @@ -366,7 +366,7 @@ Document 'README' -With 'Azure.TemplateSchema' { if ($null -ne $definition.AdditionalProperties -and $definition.AdditionalProperties -ne $false) { "**$($LocalizedData.AdditionalProperties)**" - $(global:GetDefinitionReferenceMarkdownLink $definition.AdditionalProperties.'$ref') + If($null -eq $definition.AdditionalProperties.'$ref') {$definition.AdditionalProperties.type} Else {$(global:GetDefinitionReferenceMarkdownLink $definition.AdditionalProperties.'$ref')} } if($null -ne $definition.Discriminator) {