Added ability to detect optionality for each Parameter (#68)

vicperdana · BernieWhite · web-flow · commit a85b88dfd204 · 2021-03-30T17:40:54.000+11:00
Added ability to detect "Required" or "Optional for each parameter. Closes #55 - Detects if parameter is either "Optional" or "Required" based on the availability of DefaultValue or AllowedValues - Added a "Required" column - Added "Required" and "Optional" badge for each parameter Co-authored-by: Bernie White <bewhite@microsoft.com>
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,9 @@
 # Change log
 
 ## Unreleased
+- General improvements:
+  - Added ability to detect "Required" or "Optional for each parameter. [#55](https://github.com/Azure/PSDocs.Azure/issues/55)
+    - Detects if parameter is either "Optional" or "Required" based on the availability of `DefaultValue` or `AllowedValues`
 
 ## v0.3.0-B2103011 (pre-release)
 
diff --git a/src/PSDocs.Azure/docs/Azure.Template.Doc.ps1 b/src/PSDocs.Azure/docs/Azure.Template.Doc.ps1
@@ -20,12 +20,14 @@ function global:GetTemplateParameter {
                 Description = ''
                 DefaultValue = $Null
                 AllowedValues = $Null
+                Required = $Null
             }
             if ([bool]$property.Value.PSObject.Properties['metadata'] -and [bool]$property.Value.metadata.PSObject.Properties['description']) {
                 $result.Description = $property.Value.metadata.description;
             }
             if ([bool]$property.Value.PSObject.Properties['defaultValue']) {
                 $result.DefaultValue = $property.Value.defaultValue;
+                $result.Required = "Optional"
             }
             if ([bool]$property.Value.PSObject.Properties['allowedValues']) {
                 $result.AllowedValues = $property.Value.allowedValues;
@@ -232,11 +234,24 @@ Document 'README' {
 
     # Add table and detail for each parameter
     Section $LocalizedData.Parameters {
-        $parameters | Table -Property @{ Name = $LocalizedData.ParameterName; Expression = { $_.Name }},
-            @{ Name = $LocalizedData.Description; Expression = { $_.Description }}
+        $parameters | Table -Property @{ Name = $LocalizedData.ParameterName; Expression = { $_.Name }}, 
+        @{ Name = $LocalizedData.Required; Expression = { 
+                if($_.Required) {
+                    $LocalizedData.RequiredNo
+                } 
+                else {
+                    $LocalizedData.RequiredYes
+                } 
+            }
+        }, 
+        @{ Name = $LocalizedData.Description; Expression = { $_.Description }}
 
         foreach ($parameter in $parameters) {
             Section $parameter.Name {
+                if($parameter.Required){
+                    "![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)"
+                }
+                else{ "![Parameter Setting](https://img.shields.io/badge/parameter-required-orange?style=flat-square)" }                
                 $parameter.Description;
 
                 if (![String]::IsNullOrEmpty($parameter.DefaultValue)) {
diff --git a/src/PSDocs.Azure/en/PSDocs-strings.psd1 b/src/PSDocs.Azure/en/PSDocs-strings.psd1
@@ -14,4 +14,7 @@
     DefaultTitle = 'Azure template'
     ParameterFile = 'Parameter file'
     CommandLine = 'Command line'
+    Required = 'Required'
+    RequiredYes = 'Yes'
+    RequiredNo = 'No'
 }
diff --git a/templates/acr/v1/README.md b/templates/acr/v1/README.md
@@ -6,25 +6,31 @@ Create or update a Container Registry.
 
 ## Parameters
 
-Parameter name | Description
--------------- | -----------
-registryName   | Required. The name of the container registry.
-location       | Optional. The location to deploy the container registry.
-registrySku    | Optional. The container registry SKU.
-tags           | Optional. Tags to apply to the resource.
+Parameter name | Required | Description
+-------------- | -------- | -----------
+registryName   | Yes      | Required. The name of the container registry.
+location       | No       | Optional. The location to deploy the container registry.
+registrySku    | No       | Optional. The container registry SKU.
+tags           | No       | Optional. Tags to apply to the resource.
 
 ### registryName
 
+![Parameter Setting](https://img.shields.io/badge/parameter-required-orange?style=flat-square)
+
 Required. The name of the container registry.
 
 ### location
 
+![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
+
 Optional. The location to deploy the container registry.
 
 - Default value: `[resourceGroup().location]`
 
 ### registrySku
 
+![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
+
 Optional. The container registry SKU.
 
 - Default value: `Basic`
@@ -33,6 +39,8 @@ Optional. The container registry SKU.
 
 ### tags
 
+![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
+
 Optional. Tags to apply to the resource.
 
 ## Snippets
diff --git a/templates/keyvault/v1/README.md b/templates/keyvault/v1/README.md
@@ -6,76 +6,98 @@ Create or update a Key Vault.
 
 ## Parameters
 
-Parameter name | Description
--------------- | -----------
-vaultName      | Required. The name of the Key Vault.
-location       | Optional. The Azure region to deploy to.
-accessPolicies | Optional. The access policies defined for this vault.
-useDeployment  | Optional. Determines if Azure can deploy certificates from this Key Vault.
-useTemplate    | Optional. Determines if templates can reference secrets from this Key Vault.
-useDiskEncryption | Optional. Determines if this Key Vault can be used for Azure Disk Encryption.
-useSoftDelete  | Optional. Determine if soft delete is enabled on this Key Vault.
-usePurgeProtection | Optional. Determine if purge protection is enabled on this Key Vault.
-networkAcls    | Optional. The network firewall defined for this vault.
-workspaceId    | Optional. The workspace to store audit logs.
-tags           | Optional. Tags to apply to the resource.
+Parameter name | Required | Description
+-------------- | -------- | -----------
+vaultName      | Yes      | Required. The name of the Key Vault.
+location       | No       | Optional. The Azure region to deploy to.
+accessPolicies | No       | Optional. The access policies defined for this vault.
+useDeployment  | No       | Optional. Determines if Azure can deploy certificates from this Key Vault.
+useTemplate    | No       | Optional. Determines if templates can reference secrets from this Key Vault.
+useDiskEncryption | No       | Optional. Determines if this Key Vault can be used for Azure Disk Encryption.
+useSoftDelete  | No       | Optional. Determine if soft delete is enabled on this Key Vault.
+usePurgeProtection | No       | Optional. Determine if purge protection is enabled on this Key Vault.
+networkAcls    | No       | Optional. The network firewall defined for this vault.
+workspaceId    | No       | Optional. The workspace to store audit logs.
+tags           | No       | Optional. Tags to apply to the resource.
 
 ### vaultName
 
+![Parameter Setting](https://img.shields.io/badge/parameter-required-orange?style=flat-square)
+
 Required. The name of the Key Vault.
 
 ### location
 
+![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
+
 Optional. The Azure region to deploy to.
 
 - Default value: `[resourceGroup().location]`
 
 ### accessPolicies
 
+![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
+
 Optional. The access policies defined for this vault.
 
 ### useDeployment
 
+![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
+
 Optional. Determines if Azure can deploy certificates from this Key Vault.
 
 - Default value: `False`
 
 ### useTemplate
 
+![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
+
 Optional. Determines if templates can reference secrets from this Key Vault.
 
 - Default value: `False`
 
 ### useDiskEncryption
 
+![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
+
 Optional. Determines if this Key Vault can be used for Azure Disk Encryption.
 
 - Default value: `False`
 
 ### useSoftDelete
 
+![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
+
 Optional. Determine if soft delete is enabled on this Key Vault.
 
 - Default value: `True`
 
 ### usePurgeProtection
 
+![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
+
 Optional. Determine if purge protection is enabled on this Key Vault.
 
 - Default value: `True`
 
 ### networkAcls
 
+![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
+
 Optional. The network firewall defined for this vault.
 
 - Default value: `@{defaultAction=Allow; bypass=AzureServices; ipRules=System.Object[]; virtualNetworkRules=System.Object[]}`
 
 ### workspaceId
 
+![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
+
 Optional. The workspace to store audit logs.
 
 ### tags
 
+![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
+
 Optional. Tags to apply to the resource.
 
 ## Outputs
diff --git a/templates/storage/v1/README.md b/templates/storage/v1/README.md
@@ -8,35 +8,41 @@ This template deploys a Storage Account including blob containers and files shar
 
 ## Parameters
 
-Parameter name | Description
--------------- | -----------
-storageAccountName | Required. The name of the Storage Account.
-location       | Optional. The Azure region to deploy to.
-sku            | Optional. Create the Storage Account as LRS or GRS.
-suffixLength   | Optional. Determine how many additional characters are added to the storage account name as a suffix.
-containers     | Optional. An array of storage containers to create on the storage account.
-lifecycleRules | Optional. An array of lifecycle management policies for the storage account.
-blobSoftDeleteDays | Optional. The number of days to retain deleted blobs. When set to 0, soft delete is disabled.
-containerSoftDeleteDays | Optional. The number of days to retain deleted containers. When set to 0, soft delete is disabled.
-shares         | Optional. An array of file shares to create on the storage account.
-useLargeFileShares | Optional. Determines if large file shares are enabled. This can not be disabled once enabled.
-shareSoftDeleteDays | Optional. The number of days to retain deleted shares. When set to 0, soft delete is disabled.
-allowBlobPublicAccess | Optional. Determines if any containers can be configured with the anonymous access types of blob or container.
-keyVaultPrincipalId | Optional. Set to the objectId of Azure Key Vault to delegated permission for use with Key Managed Storage Accounts.
-tags           | Optional. Tags to apply to the resource.
+Parameter name | Required | Description
+-------------- | -------- | -----------
+storageAccountName | Yes      | Required. The name of the Storage Account.
+location       | No       | Optional. The Azure region to deploy to.
+sku            | No       | Optional. Create the Storage Account as LRS or GRS.
+suffixLength   | No       | Optional. Determine how many additional characters are added to the storage account name as a suffix.
+containers     | No       | Optional. An array of storage containers to create on the storage account.
+lifecycleRules | No       | Optional. An array of lifecycle management policies for the storage account.
+blobSoftDeleteDays | No       | Optional. The number of days to retain deleted blobs. When set to 0, soft delete is disabled.
+containerSoftDeleteDays | No       | Optional. The number of days to retain deleted containers. When set to 0, soft delete is disabled.
+shares         | No       | Optional. An array of file shares to create on the storage account.
+useLargeFileShares | No       | Optional. Determines if large file shares are enabled. This can not be disabled once enabled.
+shareSoftDeleteDays | No       | Optional. The number of days to retain deleted shares. When set to 0, soft delete is disabled.
+allowBlobPublicAccess | No       | Optional. Determines if any containers can be configured with the anonymous access types of blob or container.
+keyVaultPrincipalId | No       | Optional. Set to the objectId of Azure Key Vault to delegated permission for use with Key Managed Storage Accounts.
+tags           | No       | Optional. Tags to apply to the resource.
 
 ### storageAccountName
 
+![Parameter Setting](https://img.shields.io/badge/parameter-required-orange?style=flat-square)
+
 Required. The name of the Storage Account.
 
 ### location
 
+![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
+
 Optional. The Azure region to deploy to.
 
 - Default value: `[resourceGroup().location]`
 
 ### sku
 
+![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
+
 Optional. Create the Storage Account as LRS or GRS.
 
 - Default value: `Standard_LRS`
@@ -45,58 +51,80 @@ Optional. Create the Storage Account as LRS or GRS.
 
 ### suffixLength
 
+![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
+
 Optional. Determine how many additional characters are added to the storage account name as a suffix.
 
 - Default value: `0`
 
 ### containers
 
+![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
+
 Optional. An array of storage containers to create on the storage account.
 
 ### lifecycleRules
 
+![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
+
 Optional. An array of lifecycle management policies for the storage account.
 
 ### blobSoftDeleteDays
 
+![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
+
 Optional. The number of days to retain deleted blobs. When set to 0, soft delete is disabled.
 
 - Default value: `0`
 
 ### containerSoftDeleteDays
 
+![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
+
 Optional. The number of days to retain deleted containers. When set to 0, soft delete is disabled.
 
 - Default value: `0`
 
 ### shares
 
+![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
+
 Optional. An array of file shares to create on the storage account.
 
 ### useLargeFileShares
 
+![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
+
 Optional. Determines if large file shares are enabled. This can not be disabled once enabled.
 
 - Default value: `False`
 
 ### shareSoftDeleteDays
 
+![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
+
 Optional. The number of days to retain deleted shares. When set to 0, soft delete is disabled.
 
 - Default value: `0`
 
 ### allowBlobPublicAccess
 
+![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
+
 Optional. Determines if any containers can be configured with the anonymous access types of blob or container.
 
 - Default value: `False`
 
 ### keyVaultPrincipalId
 
+![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
+
 Optional. Set to the objectId of Azure Key Vault to delegated permission for use with Key Managed Storage Accounts.
 
 ### tags
 
+![Parameter Setting](https://img.shields.io/badge/parameter-optional-green?style=flat-square)
+
 Optional. Tags to apply to the resource.
 
 ## Outputs

Original file line number	Diff line number	Diff line change
`@@ -14,4 +14,7 @@`
`14`	`14`	`DefaultTitle = 'Azure template'`
`15`	`15`	`ParameterFile = 'Parameter file'`
`16`	`16`	`CommandLine = 'Command line'`
	`17`	`+ Required = 'Required'`
	`18`	`+ RequiredYes = 'Yes'`
	`19`	`+ RequiredNo = 'No'`
`17`	`20`	`}`