Add doc generation for inspec resources

Author: slevenick

provider/inspec.rb

@@ -21,6 +21,7 @@
 module Provider
   # Code generator for Example Cookbooks that manage Google Cloud Platform
   # resources.
+  # rubocop:disable Metrics/ClassLength
   class Inspec < Provider::Core
     include Google::RubyUtils
     # Settings for the provider
@@ -54,6 +55,17 @@ def generate_resource(data)
         out_file: \
           File.join(target_folder, "google_#{data[:product_name]}_#{name}".pluralize + '.rb')
       )
+      generate_documentation(data)
+    end
+
+     # Generates InSpec markdown documents for the resource
+    def generate_documentation(data)
+      name = data[:object].name.underscore
+      docs_folder = File.join(data[:output_folder], 'docs', 'resources')
+      generate_resource_file data.clone.merge(
+        default_template: 'templates/inspec/doc-template.md.erb',
+        out_file: File.join(docs_folder, "google_#{data[:product_name]}_#{name}.md")
+      )
     end
 
     # Format a url that may be include newlines into a single line
@@ -161,5 +173,22 @@ def nested_object_requires(nested_object_type)
         [nested_object_type.__resource.name, nested_object_type.name.underscore].join('_')
       ).downcase
     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
+      # rubocop:disable Style/GuardClause
+      if typed_array?(property)
+        return property.item_type.properties.map \
+          { |prop| "    * `#{prop.name}`: #{prop.description}" }.join("\n")
+      end
+    end
+    # rubocop:enable Style/GuardClause
   end
 end

templates/inspec/doc-template.md.erb

@@ -0,0 +1,19 @@
+<% autogen_exception -%>
+
+---
+title: About the <%= object.name -%> resource
+platform: gcp
+---
+
+## Syntax
+A `<%= resource_name(object, product_ns) -%>` is used to test a Google <%= object.name -%> resource
+
+TODO: Examples
+
+## 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,10 @@
 
 <%= lines(autogen_notice :ruby) -%>
 
+<%
+  requires = generate_requires(nested_properties)
+-%>
+<%= lines(emit_requires(requires)) -%>
 module Google
   module <%= product_ns %>
     module Property

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'