Support Terraform samples (#110)

Author: anthony-c-martin

docs/configuration.md

@@ -31,4 +31,5 @@ For example, [remarks/microsoft.resources/remarks.json](../settings/remarks/micr
 * `DeploymentRemarks`: Can be used to add custom markdown with information on deploying a particular resource type. For example, explaining some of the quirks.
 * `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.
+* `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.
+* `TerraformSamples`: A list of `.tf` files that will be added as samples to documentation.

settings/schemas/remarks.schema.json

@@ -28,6 +28,12 @@
       "items": {
         "$ref": "#/definitions/CodeSample"
       }
+    },
+    "TerraformSamples": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/CodeSample"
+      }
     }
   },
   "additionalProperties": false,

src/Directory.Packages.props

@@ -11,6 +11,7 @@
     <PackageVersion Include="Azure.Bicep.Types" Version="0.5.110" />
     <PackageVersion Include="Azure.Bicep.Types.Az" Version="0.2.727" />
     <PackageVersion Include="Azure.Deployments.Testing.Utilities" Version="1.473.0" />
+    <PackageVersion Include="Microsoft.PowerPlatform.ResourceStack" Version="7.0.0.2076" />
     <PackageVersion Include="CommandLineParser" Version="2.9.1" />
     <PackageVersion Include="MSTest" Version="3.10.2" />
     <PackageVersion Include="System.IO.Abstractions" Version="22.0.14" />

src/TemplateRefGenerator/Config/RemarksLoader.cs

@@ -52,10 +52,11 @@ public record RemarksFile(
         ImmutableArray<ResourceRemark>? ResourceRemarks,
         ImmutableArray<PropertyRemark>? PropertyRemarks,
         ImmutableArray<DeploymentRemark>? DeploymentRemarks,
-        ImmutableArray<CodeSample>? BicepSamples)
+        ImmutableArray<CodeSample>? BicepSamples,
+        ImmutableArray<CodeSample>? TerraformSamples)
     {
         public static RemarksFile Empty
-            => new(null, null, null, null);
+            => new(null, null, null, null, null);
 
         public IEnumerable<ResourceRemark> GetResourceRemarks(MarkdownGenerator.ResourceMetadata resource)
             => (ResourceRemarks ?? [])
@@ -78,6 +79,11 @@ public IEnumerable<CodeSample> GetBicepSamples(MarkdownGenerator.ResourceMetadat
                 .Where(r => StringComparer.OrdinalIgnoreCase.Equals(resource.ResourceType, r.ResourceType))
                 .Where(r => FilterApiVersions(resource, r.ApiVersion));
 
+        public IEnumerable<CodeSample> GetTerraformSamples(MarkdownGenerator.ResourceMetadata resource)
+            => (TerraformSamples ?? [])
+                .Where(r => StringComparer.OrdinalIgnoreCase.Equals(resource.ResourceType, r.ResourceType))
+                .Where(r => FilterApiVersions(resource, r.ApiVersion));
+
         private static bool FilterApiVersions(MarkdownGenerator.ResourceMetadata resource, ApiVersionRequirement? apiVersionRequirement)
             => (apiVersionRequirement?.Minimum is null || ApiVersionComparer.Instance.Compare(apiVersionRequirement.Minimum, resource.ApiVersion) >= 0) &&
             (apiVersionRequirement?.Maximum is null || ApiVersionComparer.Instance.Compare(apiVersionRequirement.Maximum, resource.ApiVersion) <= 0);

src/TemplateRefGenerator/Generators/MarkdownGenerator.cs

@@ -502,7 +502,7 @@ Set the **{discObjectType.Discriminator}** property to specify the type of objec
         return sb.ToString();
     }
 
-    private static string GetTerraformZone(ConfigLoader configLoader, ResourceMetadata resource, ImmutableArray<NamedType> namedTypes, RemarksFile remarks, int anchorIndex)
+    private static string GetTerraformZone(ConfigLoader configLoader, RemarksLoader remarksLoader, ResourceMetadata resource, ImmutableArray<NamedType> namedTypes, RemarksFile remarks, int anchorIndex)
     {
         var sb = new StringBuilder();
         sb.Append($"""
@@ -591,6 +591,7 @@ Set the **{discObjectType.Discriminator}** property to specify the type of objec
         ]));
 
         sb.Append(GenerateOptionalSection("Usage Examples", [
+            GetTerraformSamplesSection(remarksLoader, resource, remarks),
             GetAvmSection(configLoader.GetSamples(), AvmLinkType.Terraform, resource),
         ]));
 
@@ -605,9 +606,9 @@ Set the **{discObjectType.Discriminator}** property to specify the type of objec
 
     private static string? GetBicepSamplesSection(RemarksLoader remarksLoader, ResourceMetadata resource, RemarksFile remarks)
     {
-        var bicepSamples = remarks.GetBicepSamples(resource).ToArray();
+        var samples = remarks.GetBicepSamples(resource).ToArray();
 
-        if (!bicepSamples.Any())
+        if (!samples.Any())
         {
             return null;
         }
@@ -619,7 +620,7 @@ Set the **{discObjectType.Discriminator}** property to specify the type of objec
 
 """);
 
-        foreach (var sample in bicepSamples)
+        foreach (var sample in samples)
         {
             sb.Append($"""
 {sample.Description}
@@ -628,6 +629,37 @@ Set the **{discObjectType.Discriminator}** property to specify the type of objec
 {remarksLoader.GetCodeSample(resource.Provider, sample)}
 ```
 
+""");
+        }
+
+        return sb.ToString();
+    }
+
+    private static string? GetTerraformSamplesSection(RemarksLoader remarksLoader, ResourceMetadata resource, RemarksFile remarks)
+    {
+        var samples = remarks.GetTerraformSamples(resource).ToArray();
+
+        if (!samples.Any())
+        {
+            return null;
+        }
+
+        var sb = new StringBuilder();
+        sb.Append($"""
+### Terraform Samples
+
+
+""");
+
+        foreach (var sample in samples)
+        {
+            sb.Append($"""
+{sample.Description}
+
+```tf
+{remarksLoader.GetCodeSample(resource.Provider, sample)}
+```
+
 """);
         }
 
@@ -1004,7 +1036,7 @@ public static string GenerateMarkdown(GroupedTypes groupedTypes, ResourceType re
 {GetResourceRemarks(resource, remarks)}
 {GetBicepZone(configLoader, remarksLoader, resource, namedTypes, remarks, 0)}
 {GetArmTemplateZone(configLoader, resource, namedTypes, remarks, 1)}
-{GetTerraformZone(configLoader, resource, namedTypes, remarks, 2)}
+{GetTerraformZone(configLoader, remarksLoader, resource, namedTypes, remarks, 2)}
 """;
     }
 }