Add interpolation of Terraform examples and migrate Address to it. (#423)

Merged PR #423.

Author: rileykarson

build/terraform

@@ -15,32 +15,17 @@
 overrides: !ruby/object:Provider::ResourceOverrides
   Address: !ruby/object:Provider::Terraform::ResourceOverride
     id_format: "{{project}}/{{region}}/{{name}}"
-    examples: |
-      ```hcl
-      resource "google_compute_address" "default" {
-        name = "my-address"
-      }
-      ```
-      ```hcl
-      resource "google_compute_network" "default" {
-        name = "my-network"
-      }
-
-      resource "google_compute_subnetwork" "default" {
-        name          = "my-subnet"
-        ip_cidr_range = "10.0.0.0/16"
-        region        = "us-central1"
-        network       = "${google_compute_network.default.self_link}"
-      }
-
-      resource "google_compute_address" "internal_with_subnet_and_address" {
-        name         = "my-internal-address"
-        subnetwork   = "${google_compute_subnetwork.default.self_link}"
-        address_type = "INTERNAL"
-        address      = "10.0.42.42"
-        region       = "us-central1"
-      }
-      ```
+    example:
+     - !ruby/object:Provider::Terraform::Examples
+      name: "address_basic"
+      vars_documentation:
+        address_name: "my-address"
+     - !ruby/object:Provider::Terraform::Examples
+      name: "address_with_subnetwork"
+      vars_documentation:
+        address_name: "my-internal-address"
+        network_name: "my-network"
+        subnetwork_name: "my-subnet"
     properties:
       address: !ruby/object:Provider::Terraform::PropertyOverride
         default_from_api: true

products/compute/terraform.yaml

@@ -12,6 +12,7 @@
 # limitations under the License.
 
 require 'api/object'
+require 'compile/core'
 require 'provider/abstract_core'
 require 'provider/property_override'
 
@@ -42,6 +43,39 @@ def validate
       end
     end
 
+    # Generates configs to be shown as examples in docs from a template
+    class Examples < Api::Object
+      include Compile::Core
+
+      # The name of the example in lower snake_case.
+      # Generally takes the form of the resource name followed by some detail
+      # about the specific test. For example, "address_with_subnetwork".
+      # The template for the example is expected at the path
+      # "templates/terraform/examples/{{name}}.tf.erb"
+      attr_reader :name
+
+      # vars_documentation is a Hash from template variable names to output
+      # variable names
+      attr_reader :vars_documentation
+
+      def config_documentation
+        body = lines(compile_file(
+                       vars_documentation,
+                       "templates/terraform/examples/#{name}.tf.erb"
+        ))
+        lines(compile_file(
+                { content: body },
+                'templates/terraform/examples/base_configs/documentation.tf.erb'
+        ))
+      end
+
+      def validate
+        super
+        check_property :name, String
+        check_property :vars_documentation, Hash
+      end
+    end
+
     # Inserts custom code into terraform resources.
     class CustomCode < Api::Object
       # Collection of fields allowed in the CustomCode section for

provider/terraform/custom_code.rb

@@ -31,7 +31,13 @@ module OverrideProperties
       # resource.
       attr_reader :mutex
 
+      # Deprecated - examples in documentation
+      # TODO(rileykarson): Remove examples and replace them with new examples
       attr_reader :examples
+
+      # New examples in documentation - will take the "examples" name when
+      # old-style examples are gone.
+      attr_reader :example
     end
 
     # A class to control overridden properties on terraform.yaml in lieu of
@@ -50,6 +56,8 @@ def validate
         check_property :id_format, String
 
         check_optional_property :examples, String
+        check_optional_property :example, Array
+
         check_optional_property :custom_code, Provider::Terraform::CustomCode
         check_optional_property :docs, Provider::Terraform::Docs
         check_property :import_format, Array

provider/terraform/resource_override.rb

@@ -0,0 +1,3 @@
+resource "google_compute_address" "default" {
+  name = "<%= ctx["address_name"] %>"
+}

templates/terraform/examples/address_basic.tf.erb

@@ -0,0 +1,18 @@
+resource "google_compute_network" "default" {
+  name = "<%= ctx["network_name"] %>"
+}
+
+resource "google_compute_subnetwork" "default" {
+  name          = "<%= ctx["subnetwork_name"] %>"
+  ip_cidr_range = "10.0.0.0/16"
+  region        = "us-central1"
+  network       = "${google_compute_network.default.self_link}"
+}
+
+resource "google_compute_address" "internal_with_subnet_and_address" {
+  name         = "<%= ctx["address_name"] %>"
+  subnetwork   = "${google_compute_subnetwork.default.self_link}"
+  address_type = "INTERNAL"
+  address      = "10.0.42.42"
+  region       = "us-central1"
+}

templates/terraform/examples/address_with_subnetwork.tf.erb

@@ -0,0 +1,3 @@
+```hcl
+<%= ctx[:content] -%>
+```

templates/terraform/examples/base_configs/documentation.tf.erb

@@ -75,6 +75,13 @@ To get more information about <%= object.name -%>, see:
 <%= "\n" + object.examples -%>
 
 <% end -%>
+<% unless object.example.nil? -%>
+## Example Usage
+
+<% object.example.each do |example| -%>
+<%= example.config_documentation -%>
+<%- end %>
+<%- end -%>
 ## Argument Reference
 
 The following arguments are supported: