Add support for custom ARM template examples and reorder sections

docs/configuration.md

@@ -32,4 +32,5 @@ For example, [remarks/microsoft.resources/remarks.json](../settings/remarks/micr
 * `ResourceRemarks`: Can be used to add custom remarks in markdown format about a particular resource type. See [here](https://github.com/Azure/bicep-refdocs-generator/blob/016143aa9375ba0ce62255fed1fad8905cfe75bf/src/TemplateRefGenerator.Tests/Files/markdown/microsoft.keyvault/2023-07-01/vaults.md?plain=1#L29-L35) for an example of what the customized output looks like.
 * `PropertyRemarks`: Can be used to replace the description markdown for a particular resource type property.
 * `BicepSamples`: A list of `.bicep` files that will be added as samples to documentation. See [here](https://github.com/Azure/bicep-refdocs-generator/blob/016143aa9375ba0ce62255fed1fad8905cfe75bf/src/TemplateRefGenerator.Tests/Files/markdown/microsoft.resources/2024-07-01/resourcegroups.md?plain=1#L61-L75) for an example of what the customized looks like.
+* `ArmTemplateSamples`: A list of ARM template `.json` files that will be added as samples to documentation.
 * `TerraformSamples`: A list of `.tf` files that will be added as samples to documentation.

settings/remarks/microsoft.horizondb/remarks.json

@@ -83,5 +83,47 @@
       "Path": "samples/clusters/pools/replicas/add-specific-availability-zone.bicep",
       "Description": "Add a replica in a specific availability zone to a pool."
     }
+  ],
+  "ArmTemplateSamples": [
+    {
+      "ResourceType": "Microsoft.HorizonDB/clusters",
+      "Path": "samples/clusters/create.json",
+      "Description": "Create a cluster."
+    },
+    {
+      "ResourceType": "Microsoft.HorizonDB/clusters",
+      "Path": "samples/clusters/update-administrator-login-password.json",
+      "Description": "Update a cluster's administrator login password."
+    },
+    {
+      "ResourceType": "Microsoft.HorizonDB/clusters",
+      "Path": "samples/clusters/scale-cluster-vertically.json",
+      "Description": "Scale a cluster vertically."
+    },
+    {
+      "ResourceType": "Microsoft.HorizonDB/clusters",
+      "Path": "samples/clusters/connect-parameter-group-to-cluster.json",
+      "Description": "Connect a parameter group to a cluster."
+    },
+    {
+      "ResourceType": "Microsoft.HorizonDB/parameterGroups",
+      "Path": "samples/parametergroups/create.json",
+      "Description": "Create a parameter group."
+    },
+    {
+      "ResourceType": "Microsoft.HorizonDB/clusters/pools/firewallRules",
+      "Path": "samples/clusters/pools/firewallrules/create.json",
+      "Description": "Create a firewall rule on a cluster."
+    },
+    {
+      "ResourceType": "Microsoft.HorizonDB/clusters/pools/replicas",
+      "Path": "samples/clusters/pools/replicas/add-no-specific-availability-zone.json",
+      "Description": "Add a replica without a specific availability zone to a pool."
+    },
+    {
+      "ResourceType": "Microsoft.HorizonDB/clusters/pools/replicas",
+      "Path": "samples/clusters/pools/replicas/add-specific-availability-zone.json",
+      "Description": "Add a replica in a specific availability zone to a pool."
+    }
   ]
 }

settings/remarks/microsoft.horizondb/samples/clusters/connect-parameter-group-to-cluster.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
+  "contentVersion": "1.0.0.0",
+  "parameters": {
+    "location": {
+      "type": "string",
+      "defaultValue": "eastus",
+      "metadata": {
+        "description": "The location for the cluster"
+      }
+    },
+    "clusterName": {
+      "type": "string",
+      "metadata": {
+        "description": "The name for the cluster"
+      }
+    },
+    "createMode": {
+      "type": "string",
+      "defaultValue": "Update",
+      "metadata": {
+        "description": "The create mode for cluster"
+      }
+    },
+    "parameterGroupId": {
+      "type": "string",
+      "metadata": {
+        "description": "The identifier of the parameter group to connect to the cluster"
+      }
+    }
+  },
+  "resources": [
+    {
+      "type": "Microsoft.HorizonDB/clusters",
+      "apiVersion": "2026-01-20-preview",
+      "name": "[parameters('clusterName')]",
+      "location": "[parameters('location')]",
+      "properties": {
+        "createMode": "[parameters('createMode')]",
+        "parameterGroup": {
+          "id": "[parameters('parameterGroupId')]"
+        }
+      }
+    }
+  ]
+}

settings/remarks/microsoft.horizondb/samples/clusters/create.json

@@ -0,0 +1,93 @@
+{
+  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
+  "contentVersion": "1.0.0.0",
+  "parameters": {
+    "location": {
+      "type": "string",
+      "defaultValue": "eastus",
+      "metadata": {
+        "description": "The location for the cluster"
+      }
+    },
+    "clusterName": {
+      "type": "string",
+      "metadata": {
+        "description": "The name for the cluster"
+      }
+    },
+    "tags": {
+      "type": "object",
+      "defaultValue": {
+        "env": "dev"
+      },
+      "metadata": {
+        "description": "The tags for the cluster"
+      }
+    },
+    "createMode": {
+      "type": "string",
+      "defaultValue": "Create",
+      "metadata": {
+        "description": "The create mode for cluster"
+      }
+    },
+    "version": {
+      "type": "int",
+      "defaultValue": 17,
+      "metadata": {
+        "description": "The major version of server"
+      }
+    },
+    "administratorLogin": {
+      "type": "string",
+      "metadata": {
+        "description": "The administrator login name for cluster"
+      }
+    },
+    "administratorLoginPassword": {
+      "type": "secureString",
+      "metadata": {
+        "description": "The administrator login password for cluster"
+      }
+    },
+    "vCores": {
+      "type": "int",
+      "defaultValue": 4,
+      "metadata": {
+        "description": "The number of vCores for each replica of the cluster"
+      }
+    },
+    "replicaCount": {
+      "type": "int",
+      "defaultValue": 2,
+      "metadata": {
+        "description": "The number of replicas for the cluster, including the primary replica, which is the only one in which writes are allowed. The other replicas are read-only."
+      }
+    },
+    "zonePlacementPolicy": {
+      "type": "string",
+      "defaultValue": "BestEffort",
+      "metadata": {
+        "description": "The name of the SKU for cluster"
+      }
+    }
+  },
+  "resources": [
+    {
+      "type": "Microsoft.HorizonDB/clusters",
+      "apiVersion": "2026-01-20-preview",
+      "name": "[parameters('clusterName')]",
+      "location": "[parameters('location')]",
+      "tags": "[parameters('tags')]",
+      "properties": {
+        "createMode": "[parameters('createMode')]",
+        "version": "[parameters('version')]",
+        "administratorLogin": "[parameters('administratorLogin')]",
+        "administratorLoginPassword": "[parameters('administratorLoginPassword')]",
+        "vCores": "[parameters('vCores')]",
+        "replicaCount": "[parameters('replicaCount')]",
+        "zonePlacementPolicy": "[parameters('zonePlacementPolicy')]"
+      }
+    }
+  ]
+}

settings/remarks/microsoft.horizondb/samples/clusters/pools/firewallrules/create.json

@@ -0,0 +1,106 @@
+{
+  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
+  "contentVersion": "1.0.0.0",
+  "parameters": {
+    "clusterName": {
+      "type": "string",
+      "metadata": {
+        "description": "The name for the cluster"
+      }
+    },
+    "poolName": {
+      "type": "string",
+      "defaultValue": "DefaultPool",
+      "metadata": {
+        "description": "The name for the pool"
+      }
+    },
+    "firewallRuleName": {
+      "type": "string",
+      "defaultValue": "DataAnalyticsDepartment",
+      "metadata": {
+        "description": "The name for the firewall rule"
+      }
+    },
+    "firewallRuleStartIp": {
+      "type": "string",
+      "defaultValue": "10.0.0.1",
+      "metadata": {
+        "description": "The start IP address for the firewall rule"
+      }
+    },
+    "firewallRuleEndIp": {
+      "type": "string",
+      "defaultValue": "10.0.0.10",
+      "metadata": {
+        "description": "The end IP address for the firewall rule"
+      }
+    },
+    "firewallRuleDescription": {
+      "type": "string",
+      "defaultValue": "Allow all IP addresses from the Data Analytics department",
+      "metadata": {
+        "description": "The description for the firewall rule"
+      }
+    },
+    "createMode": {
+      "type": "string",
+      "defaultValue": "Create",
+      "metadata": {
+        "description": "The create mode for cluster"
+      }
+    },
+    "version": {
+      "type": "int",
+      "defaultValue": 17,
+      "metadata": {
+        "description": "The major version of server"
+      }
+    },
+    "administratorLogin": {
+      "type": "string",
+      "metadata": {
+        "description": "The administrator login name for cluster"
+      }
+    },
+    "administratorLoginPassword": {
+      "type": "secureString",
+      "metadata": {
+        "description": "The administrator login password for cluster"
+      }
+    },
+    "vCores": {
+      "type": "int",
+      "defaultValue": 4,
+      "metadata": {
+        "description": "The number of vCores for each replica of the cluster"
+      }
+    },
+    "replicaCount": {
+      "type": "int",
+      "defaultValue": 2,
+      "metadata": {
+        "description": "The number of replicas for the cluster, including the primary replica, which is the only one in which writes are allowed. The other replicas are read-only."
+      }
+    },
+    "zonePlacementPolicy": {
+      "type": "string",
+      "defaultValue": "BestEffort",
+      "metadata": {
+        "description": "The name of the SKU for cluster"
+      }
+    }
+  },
+  "resources": [
+    {
+      "type": "Microsoft.HorizonDB/clusters/pools/firewallRules",
+      "apiVersion": "2026-01-20-preview",
+      "name": "[format('{0}/{1}/{2}', parameters('clusterName'), parameters('poolName'), parameters('firewallRuleName'))]",
+      "properties": {
+        "startIp": "[parameters('firewallRuleStartIp')]",
+        "endIp": "[parameters('firewallRuleEndIp')]",
+        "description": "[parameters('firewallRuleDescription')]"
+      }
+    }
+  ]
+}

settings/remarks/microsoft.horizondb/samples/clusters/pools/replicas/add-no-specific-availability-zone.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
+  "contentVersion": "1.0.0.0",
+  "parameters": {
+    "clusterName": {
+      "type": "string",
+      "metadata": {
+        "description": "The name for the cluster"
+      }
+    },
+    "poolName": {
+      "type": "string",
+      "defaultValue": "DefaultPool",
+      "metadata": {
+        "description": "The name for the pool"
+      }
+    },
+    "replicaName": {
+      "type": "string",
+      "metadata": {
+        "description": "The name for the replica"
+      }
+    },
+    "role": {
+      "type": "string",
+      "defaultValue": "Read",
+      "metadata": {
+        "description": "The role for the replica"
+      }
+    },
+    "availabilityZone": {
+      "type": "string",
+      "defaultValue": "1",
+      "metadata": {
+        "description": "The availability zone for the replica"
+      }
+    }
+  },
+  "resources": [
+    {
+      "type": "Microsoft.HorizonDB/clusters/pools/replicas",
+      "apiVersion": "2026-01-20-preview",
+      "name": "[format('{0}/{1}/{2}', parameters('clusterName'), parameters('poolName'), parameters('replicaName'))]",
+      "properties": {
+        "role": "[parameters('role')]",
+        "availabilityZone": "[parameters('availabilityZone')]"
+      }
+    }
+  ]
+}

settings/remarks/microsoft.horizondb/samples/clusters/pools/replicas/add-specific-availability-zone.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
+  "contentVersion": "1.0.0.0",
+  "parameters": {
+    "clusterName": {
+      "type": "string",
+      "metadata": {
+        "description": "The name for the cluster"
+      }
+    },
+    "poolName": {
+      "type": "string",
+      "defaultValue": "DefaultPool",
+      "metadata": {
+        "description": "The name for the pool"
+      }
+    },
+    "replicaName": {
+      "type": "string",
+      "metadata": {
+        "description": "The name for the replica"
+      }
+    },
+    "role": {
+      "type": "string",
+      "defaultValue": "Read",
+      "metadata": {
+        "description": "The role for the replica"
+      }
+    }
+  },
+  "resources": [
+    {
+      "type": "Microsoft.HorizonDB/clusters/pools/replicas",
+      "apiVersion": "2026-01-20-preview",
+      "name": "[format('{0}/{1}/{2}', parameters('clusterName'), parameters('poolName'), parameters('replicaName'))]",
+      "properties": {
+        "role": "[parameters('role')]"
+      }
+    }
+  ]
+}