(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

README.md

@@ -177,18 +177,18 @@ For details about Strings JSON output, see [Strings JSON schema](https://github.
 
 Strings can also produce documentation in Markdown and then either generate an `.md` file or print Markdown to stdout. The generated markdown layout has been reviewed and approved by Puppet's tech pubs team and is the same that is used in Puppet Supported modules.
 
-To generate Markdown documentation to a file, run:
+To generate REFERENCE.md:
-
-```
-$ puppet strings generate --format markdown --out REFERENCE.md
-```
-
-To generate and then print Markdown documentation to stdout, run:
 
 ```
 $ puppet strings generate --format markdown
 ```
 
+To write Markdown documentation to another file, use the --out option:
+
+```
+$ puppet strings generate --format markdown --out docs/INFO.md
+```
+
 ### Output documents to GitHub Pages
 
 To generate documents and then make them available on [GitHub Pages](https://pages.github.com/), use the Strings rake task `strings:gh_pages:update`. See [Rake tasks](#rake-tasks) for setup and usage details.
@@ -301,7 +301,7 @@ end
 
 All provider method calls, including `confine`, `defaultfor`, and `commands`, are automatically parsed and documented by Strings. The `desc` method is used to generate the docstring, and can include tags such as `@example` if written as a heredoc.
 
-Document types that use the new [Resource API](https://github.com/puppetlabs/puppet-resource_api).
+Document types that use the new [Resource API](https://github.com/puppetlabs/puppet-resource_api):
 
 ```ruby
 Puppet::ResourceApi.register_type(

lib/puppet-strings.rb

@@ -31,7 +31,11 @@ module PuppetStrings
 
     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 @@ module PuppetStrings::Markdown
     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 @@ Puppet::Face.define(:strings, '0.0.1') do
       generate_options[:markup] = markup if markup
       generate_options[:path] = options[:out] if options[:out]
       generate_options[:stdout] = options[:stdout]
-      format = options[:format] || ""
+      format = options[:format]
-      if format.casecmp('markdown').zero?
+      if format
-        generate_options[:markdown] = true
+        if format.casecmp('markdown').zero?
-      elsif format.casecmp('json').zero? || options[:emit_json] || options[:emit_json_stdout]
+          generate_options[:markdown] = true
-        generate_options[:json] = 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