(PDOC-184) block pointless output and re-add options

This makes sure the markdown doesn't include section headers that have no content. e.g. '## Classes' does not get put in if there are no classes. Also, we should deprecate --emit-json and --emit-json-stdout instead of just killing them.

Author: eputnam

lib/puppet-strings.rb

@@ -29,6 +29,7 @@ def self.generate(search_patterns = DEFAULT_SEARCH_PATTERNS, options = {})
     args << '--backtrace' if options[:backtrace]
     args << "-m#{options[:markup] || 'markdown'}"
 
+    file = nil
     if options[:json] || options[:markdown]
       file = options[:path]
       # Disable output and prevent stats/progress when writing to STDOUT
@@ -47,12 +48,12 @@ def self.generate(search_patterns = DEFAULT_SEARCH_PATTERNS, options = {})
 
     # If outputting JSON, render the output
     if options[:json]
-      render_json(options[:path])
+      render_json(file)
     end
 
     # If outputting Markdown, render the output
     if options[:markdown]
-      render_markdown(options[:path])
+      render_markdown(file)
     end
   end
 

lib/puppet-strings/markdown/puppet_classes.rb

@@ -2,12 +2,14 @@
 
 module PuppetStrings::Markdown
   module PuppetClasses
+
+    # @return [Array] list of classes
     def self.in_classes
       YARD::Registry.all(:puppet_class).sort_by!(&:name).map!(&:to_hash)
     end
 
     def self.render
-      final = "## Classes\n\n"
+      final = in_classes.length > 0 ? "## Classes\n\n" : ""
       in_classes.each do |klass|
         final << PuppetStrings::Markdown::PuppetClass.new(klass).render
       end

lib/puppet-strings/markdown/puppet_defined_types.rb

@@ -2,12 +2,14 @@
 
 module PuppetStrings::Markdown
   module PuppetDefinedTypes
+
+    # @return [Array] list of defined types
     def self.in_dtypes
       YARD::Registry.all(:puppet_defined_type).sort_by!(&:name).map!(&:to_hash)
     end
 
     def self.render
-      final = "## Defined types\n\n"
+      final = in_dtypes.length > 0 ? "## Defined types\n\n" : ""
       in_dtypes.each do |type|
         final << PuppetStrings::Markdown::PuppetDefinedType.new(type).render
       end

lib/puppet-strings/markdown/puppet_functions.rb

@@ -2,12 +2,14 @@
 
 module PuppetStrings::Markdown
   module PuppetFunctions
+
+    # @return [Array] list of functions
     def self.in_functions
       YARD::Registry.all(:puppet_function).sort_by!(&:name).map!(&:to_hash)
     end
 
     def self.render
-      final = "## Functions\n\n"
+      final = in_functions.length > 0 ? "## Functions\n\n" : ""
       in_functions.each do |func|
         final << PuppetStrings::Markdown::PuppetFunction.new(func).render
       end

lib/puppet-strings/markdown/puppet_resource_types.rb

@@ -2,12 +2,14 @@
 
 module PuppetStrings::Markdown
   module PuppetResourceTypes
+
+    # @return [Array] list of resource types
     def self.in_rtypes
       YARD::Registry.all(:puppet_type).sort_by!(&:name).map!(&:to_hash)
     end
 
     def self.render
-      final = "## Resource types\n\n"
+      final = in_rtypes.length > 0 ? "## Resource types\n\n" : ""
       in_rtypes.each do |type|
         final << PuppetStrings::Markdown::PuppetResourceType.new(type).render
       end

lib/puppet-strings/markdown/templates/table_of_contents.erb

@@ -1,22 +1,22 @@
-<% if puppet_classes -%>
+<% if puppet_classes.length > 0 -%>
 ## Classes
 <% puppet_classes.each do |klassy| -%>
 * [`<%= klassy[:name] %>`](#<%= klassy[:link] %>): <%= klassy[:desc] %>
 <% end -%>
 <% end -%>
-<% if puppet_defined_types -%>
+<% if puppet_defined_types.length > 0 -%>
 ## Defined types
 <% puppet_defined_types.each do |dtype| -%>
 * [`<%= dtype[:name] %>`](#<%= dtype[:link] %>): <%= dtype[:desc] %>
 <% end -%>
 <% end -%>
-<% if puppet_resource_types -%>
+<% if puppet_resource_types.length > 0 -%>
 ## Resource types
 <% puppet_resource_types.each do |rtype| -%>
 * [`<%= rtype[:name] %>`](#<%= rtype[:link] %>): <%= rtype[:desc] %>
 <% end -%>
 <% end -%>
-<% if puppet_functions -%>
+<% if puppet_functions.length > 0 -%>
 ## Functions
 <% puppet_functions.each do |func| -%>
 * [`<%= func[:name] %>`](#<%= func[:link] %>): <%= func[:desc] %>

lib/puppet/face/strings.rb

@@ -16,6 +16,12 @@
     option '--markup FORMAT' do
       summary "The markup format to use for docstring text (defaults to 'markdown')."
     end
+    option '--emit-json-stdout' do
+      summary 'DEPRECATED: Print JSON representation of the documentation to stdout.'
+    end
+    option '--emit-json PATH' do
+      summary 'DEPRECATED: Write JSON representation of the documentation to the given file.'
+    end
 
     summary 'Generate documentation from files.'
     arguments '[[search_pattern] ...]'
@@ -94,14 +100,20 @@ def build_generate_options(options = nil, *yard_args)
     generate_options[:yard_args] = yard_args unless yard_args.empty?
 
     if options
+      if options[:emit_json]
+        $stderr.puts "WARNING: '--emit-json PATH' is deprecated. Use '--format json --out PATH' instead."
+      end
+      if options[:emit_json_stdout]
+        $stderr.puts "WARNING: '--emit-json-stdout' is deprecated. Use '--format json' instead."
+      end
       markup = options[:markup]
       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'
+      if format.casecmp('markdown') == 0
         generate_options[:markdown] = true
-      elsif format.casecmp 'json'
+      elsif format.casecmp('json') == 0 || options[:emit_json] || options[:emit_json_stdout]
         generate_options[:json] = true
       end
     end