First pass at generating docs for resources

Author: slevenick

provider/inspec.rb

@@ -52,6 +52,10 @@ def generate_resource(data)
         default_template: 'templates/inspec/plural_resource.erb',
         out_file: File.join(target_folder, plural("google_#{data[:product_name]}_#{name}") + ".rb")
       )
+      generate_resource_file data.clone.merge(
+        default_template: 'templates/inspec/doc.md.erb',
+        out_file: File.join(target_folder, "google_#{data[:product_name]}_#{name}.md")
+      )
     end
 
     # Returns the url that this object can be retrieved from
@@ -162,12 +166,6 @@ def nested_object_requires(nested_object_type)
       ).downcase
     end
 
-    # InSpec doesn't need wrappers for primitives, so exclude them
-    def emit_requires(requires)
-      primitives = ['boolean', 'enum', 'string', 'time', 'integer', 'array', 'string_array', 'double']
-      requires.flatten.sort.uniq.reject{|r| primitives.include?(r.split('/').last)}.map { |r| "require '#{r}'" }.join("\n")
-    end
-
     def plural(word)
       # TODO use a real ruby gem for this? Pluralization is hard
       if word[-1] == 's'
@@ -178,5 +176,18 @@ def plural(word)
       end
       return word + 's'
     end
+
+    def resource_name(object, product_ns)
+      "google_#{product_ns.downcase}_#{object.name.underscore}"
+    end
+
+    def sub_property_descriptions(property)
+      if nested_object?(property)
+        return property.properties.map { |prop| "    * `#{prop.name}`: #{prop.description}" }.join("\n")
+      end
+      if typed_array?(property)
+        return property.item_type.properties.map { |prop| "    * `#{prop.name}`: #{prop.description}" }.join("\n")
+      end
+    end
   end
 end

templates/inspec/doc.md.erb

@@ -0,0 +1,17 @@
+<%= lines(autogen_notice :markdown) -%>
+
+---
+title: About the <%= object.name -%> resource
+platform: gcp
+---
+
+## Syntax
+A `<%= resource_name(object, product_ns) -%>` is used to test a Google <%= object.name -%> resource
+
+## Properties
+Properties that can be accessed from the `<%= resource_name(object, product_ns) -%>` resource:
+<% object.properties.each do |prop| -%>
+  * `<%= "#{prop.out_name}" -%>`, <%= "#{prop.description}" -%>
+
+<%= sub_property_descriptions(prop) -%>
+<% end -%>

templates/inspec/nested_object.erb

@@ -16,6 +16,15 @@
 
 <%= lines(autogen_notice :ruby) -%>
 
+<%
+  require 'google/string_utils'
+
+  inside_indent = 8
+
+  requires = generate_requires(nested_properties)
+  requires << 'google/hash_utils'
+-%>
+<%= lines(emit_requires(requires)) -%>
 module Google
   module <%= product_ns %>
     module Property
@@ -34,7 +43,7 @@ module Google
 <%
   if time?(prop)
       init = "Time.new(@fetched['#{prop.api_name}'])"
-  elsif primitive?(prop) || resource_ref?(prop)
+  elsif primitive?(prop)
     init = "args['#{prop.api_name}']"
   elsif typed_array?(prop)
     init = "#{prop.property_type}.parse(args['#{prop.api_name}'])"

templates/inspec/singular_resource.erb

@@ -30,7 +30,7 @@
 # A provider to manage <%= @api.name -%> resources.
 class <%= object.name -%> < Inspec.resource(1)
 
-  name 'google_<%= product_ns.downcase -%>_<%= object.name.underscore -%>'
+  name '<%= resource_name(object, product_ns) -%>'
   desc '<%= object.name -%>'
   supports platform: 'gcp2'