(PDOC-184) revised cli

`puppet generate` behavior remains unchanged
`puppet generate --format markdown` now defaults to writing to
REFERENCE.md and will accept an override from --out
`puppet generate --format json` defaults to printing to stdout but will
accept the --out param

Author: eputnam

lib/puppet-strings.rb

@@ -31,7 +31,11 @@ def self.generate(search_patterns = DEFAULT_SEARCH_PATTERNS, options = {})
 
     file = nil
     if options[:json] || options[:markdown]
-      file = options[:path]
+      file = if options[:json]
+               options[:path]
+             elsif options[:markdown]
+               options[:path] || "REFERENCE.md"
+             end
       # Disable output and prevent stats/progress when writing to STDOUT
       args << '-n'
       args << '-q' unless file

lib/puppet-strings/markdown.rb

@@ -21,12 +21,15 @@ def self.generate
     final
   end
 
+  # mimicks the behavior of the json render, although path will never be nil
+  # @param [String] path path to destination file
   def self.render(path = nil)
     if path.nil?
       puts generate
       exit
     else
       File.open(path, 'w') { |file| file.write(generate) }
+      YARD::Logger.instance.debug "Wrote markdown to #{path}"
     end
   end
 end

lib/puppet/face/strings.rb

@@ -110,11 +110,15 @@ def build_generate_options(options = nil, *yard_args)
       generate_options[:markup] = markup if markup
       generate_options[:path] = options[:out] if options[:out]
       generate_options[:stdout] = options[:stdout]
-      format = options[:format] || ""
-      if format.casecmp('markdown').zero?
-        generate_options[:markdown] = true
-      elsif format.casecmp('json').zero? || options[:emit_json] || options[:emit_json_stdout]
-        generate_options[:json] = true
+      format = options[:format]
+      if format
+        if format.casecmp('markdown').zero?
+          generate_options[:markdown] = true
+        elsif format.casecmp('json').zero? || options[:emit_json] || options[:emit_json_stdout]
+          generate_options[:json] = true
+        else
+          raise RuntimeError, "Invalid format #{options[:format]}. Please select 'json' or 'markdown'."
+        end
       end
     end
     generate_options