From 131697582688364721b22e0f8a4cd34733e8a188 Mon Sep 17 00:00:00 2001
From: Eric Putnam <putnam.eric@gmail.com>
Date: Tue, 20 Feb 2018 12:12:46 -0800
Subject: [PATCH] (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                      | 16 ++++++++--------
 lib/puppet-strings.rb          |  6 +++++-
 lib/puppet-strings/markdown.rb |  3 +++
 lib/puppet/face/strings.rb     | 14 +++++++++-----
 4 files changed, 25 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index f186f01..958f806 100644
--- a/README.md
+++ b/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:
-
-```
-$ puppet strings generate --format markdown --out REFERENCE.md
-```
-
-To generate and then print Markdown documentation to stdout, run:
+To generate REFERENCE.md:
 
 ```
 $ 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(
diff --git a/lib/puppet-strings.rb b/lib/puppet-strings.rb
index 1e0bfe7..31f6338 100644
--- a/lib/puppet-strings.rb
+++ b/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
diff --git a/lib/puppet-strings/markdown.rb b/lib/puppet-strings/markdown.rb
index 6bc3b61..6370099 100644
--- a/lib/puppet-strings/markdown.rb
+++ b/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
diff --git a/lib/puppet/face/strings.rb b/lib/puppet/face/strings.rb
index 578b681..da1c458 100644
--- a/lib/puppet/face/strings.rb
+++ b/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] || ""
-      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