(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

README.md

@@ -10,6 +10,7 @@ Puppet Strings generates HTML documentation for Puppet extensions written in Pup
 | -------------- |---------------------------------------------------------------- |
 | *Code*         | [GitHub][repo]                                                  |
 | *Issues*       | [Puppet JIRA Tracker][JIRA]                                     |
+
 | *License*      | [Apache 2.0][LICENSE]                                           |
 | *Change log*   | [CHANGELOG.md][changelog]                                       |
 | *Contributing* | [CONTRIBUTING.md][contributing] and [COMMITTERS.md][committers] |
@@ -177,16 +178,16 @@ 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
+$ puppet strings generate --format markdown
 ```
 
-To generate and then print Markdown documentation to stdout, run:
+To write Markdown documentation to another file, use the --out option:
 
 ```
-$ puppet strings generate --format markdown
+$ puppet strings generate --format markdown --out docs/INFO.md
 ```
 
 ### Output documents to GitHub Pages
@@ -301,7 +302,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 @@ 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