(puppetlabs#267) Don’t show “Public X” header without contents

Previously, the “Public X” header would be displayed if there were any
private X regardless of whether there were any public X.

For example, having a private function would make both the “Public
Functions” and “Private Functions” headers appear, even if there weren’t
any public functions.

This changes it so that there are three conditions:

  * **Only public X:** no “Public” or “Private“ headers are displayed;
    the X are listed with links to their documentation. (Public is
    implied.)
  * **Only private X:** a “Private X” header is is displayed with a list
    of X. There are no links to documentation for private APIs.
  * **Both public and private X:** both “Public X” and “Private X”
    headers are displayed. The public Xs are listed with links to their
    documentation; the private Xs are just listed with no links.

In other words, if there are no private Xs, then it just lists the
public once. Otherwise, it splits them up under public/private headers
but avoids showing a header if it’s contents will be empty.

This also radically simplifies and removes a bunch of boilerplate code
around rendering these sections.

lib/puppet-strings/markdown.rb

@@ -13,21 +13,41 @@ module PuppetStrings::Markdown
   require_relative 'markdown/puppet_plans'
   require_relative 'markdown/table_of_contents'
 
+  # Get modules that handle collecting and rendering each section.
+  #
+  # Does not include the special TableOfContents module.
+  # @return [Array[module]] The modules
+  def self.groups
+    [
+      PuppetStrings::Markdown::PuppetClasses,
+      PuppetStrings::Markdown::DefinedTypes,
+      PuppetStrings::Markdown::ResourceTypes,
+      PuppetStrings::Markdown::Functions,
+      PuppetStrings::Markdown::DataTypes,
+      PuppetStrings::Markdown::PuppetTasks,
+      PuppetStrings::Markdown::PuppetPlans,
+    ]
+  end
+
   # generates markdown documentation
   # @return [String] markdown doc
   def self.generate
-    final = "# Reference\n\n"
-    final += "<!-- DO NOT EDIT: This document was generated by Puppet Strings -->\n\n"
-    final += PuppetStrings::Markdown::TableOfContents.render
-    final += PuppetStrings::Markdown::PuppetClasses.render
-    final += PuppetStrings::Markdown::DefinedTypes.render
-    final += PuppetStrings::Markdown::ResourceTypes.render
-    final += PuppetStrings::Markdown::Functions.render
-    final += PuppetStrings::Markdown::DataTypes.render
-    final += PuppetStrings::Markdown::PuppetTasks.render
-    final += PuppetStrings::Markdown::PuppetPlans.render
+    final = [
+      "# Reference\n\n",
+      "<!-- DO NOT EDIT: This document was generated by Puppet Strings -->\n\n",
+      PuppetStrings::Markdown::TableOfContents.render,
+    ]
+
+    final += self.groups.map do |group|
+      renders = group.items.reject { |item| item.private? }.map { |item| item.render }
+      if renders.empty?
+        ''
+      else
+        "## #{group.name}\n\n" + renders.join('')
+      end
+    end
 
-    final
+    final.join('')
   end
 
   # mimicks the behavior of the json render, although path will never be nil

lib/puppet-strings/markdown/data_types.rb

@@ -4,40 +4,17 @@
 
 module PuppetStrings::Markdown
   module DataTypes
+    def self.name
+      'Data types'
+    end
 
     # @return [Array] list of data types
-    def self.in_dtypes
+    def self.items
       arr = YARD::Registry.all(:puppet_data_type).map!(&:to_hash)
       arr.concat(YARD::Registry.all(:puppet_data_type_alias).map!(&:to_hash))
 
       arr.sort! { |a,b| a[:name] <=> b[:name] }
       arr.map! { |a| PuppetStrings::Markdown::DataType.new(a) }
     end
-
-    def self.contains_private?
-      result = false
-      unless in_dtypes.nil?
-        in_dtypes.find { |type| type.private? }.nil? ? false : true
-      end
-    end
-
-    def self.render
-      final = in_dtypes.length > 0 ? "## Data types\n\n" : ""
-      in_dtypes.each do |type|
-        final += type.render unless type.private?
-      end
-      final
-    end
-
-
-    def self.toc_info
-      final = ["Data types"]
-
-      in_dtypes.each do |type|
-        final.push(type.toc_info)
-      end
-
-      final
-    end
   end
 end

lib/puppet-strings/markdown/defined_types.rb

@@ -4,36 +4,14 @@
 
 module PuppetStrings::Markdown
   module DefinedTypes
+    def self.name
+      'Defined types'
+    end
 
     # @return [Array] list of defined types
-    def self.in_dtypes
+    def self.items
       arr = YARD::Registry.all(:puppet_defined_type).sort_by!(&:name).map!(&:to_hash)
       arr.map! { |a| PuppetStrings::Markdown::DefinedType.new(a) }
     end
-
-    def self.contains_private?
-      result = false
-      unless in_dtypes.nil?
-        in_dtypes.find { |type| type.private? }.nil? ? false : true
-      end
-    end
-
-    def self.render
-      final = in_dtypes.length > 0 ? "## Defined types\n\n" : ""
-      in_dtypes.each do |type|
-        final += type.render unless type.private?
-      end
-      final
-    end
-
-    def self.toc_info
-      final = ["Defined types"]
-
-      in_dtypes.each do |type|
-        final.push(type.toc_info)
-      end
-
-      final
-    end
   end
 end

lib/puppet-strings/markdown/functions.rb

@@ -4,37 +4,15 @@
 
 module PuppetStrings::Markdown
   module Functions
+    def self.name
+      'Functions'
+    end
 
     # @return [Array] list of functions
-    def self.in_functions
+    def self.items
       arr = YARD::Registry.all(:puppet_function).sort_by!(&:name).map!(&:to_hash)
       arr.map! { |a| PuppetStrings::Markdown::Function.new(a) }
     end
-
-    def self.contains_private?
-      result = false
-      unless in_functions.nil?
-        in_functions.find { |func| func.private? }.nil? ? false : true
-      end
-    end
-
-    def self.render
-      final = in_functions.length > 0 ? "## Functions\n\n" : ""
-      in_functions.each do |func|
-        final += func.render unless func.private?
-      end
-      final
-    end
-
-    def self.toc_info
-      final = ["Functions"]
-
-      in_functions.each do |func|
-        final.push(func.toc_info)
-      end
-
-      final
-    end
   end
 end
 

lib/puppet-strings/markdown/puppet_classes.rb

@@ -4,36 +4,14 @@
 
 module PuppetStrings::Markdown
   module PuppetClasses
+    def self.name
+      'Classes'
+    end
 
     # @return [Array] list of classes
-    def self.in_classes
+    def self.items
       arr = YARD::Registry.all(:puppet_class).sort_by!(&:name).map!(&:to_hash)
       arr.map! { |a| PuppetStrings::Markdown::PuppetClass.new(a) }
     end
-
-    def self.contains_private?
-      result = false
-      unless in_classes.nil?
-        in_classes.find { |klass| klass.private? }.nil? ? false : true
-      end
-    end
-
-    def self.render
-      final = in_classes.length > 0 ? "## Classes\n\n" : ""
-      in_classes.each do |klass|
-        final += klass.render unless klass.private?
-      end
-      final
-    end
-
-    def self.toc_info
-      final = ["Classes"]
-
-      in_classes.each do |klass|
-        final.push(klass.toc_info)
-      end
-
-      final
-    end
   end
 end

lib/puppet-strings/markdown/puppet_plans.rb

@@ -4,36 +4,14 @@
 
 module PuppetStrings::Markdown
   module PuppetPlans
+    def self.name
+      'Plans'
+    end
 
     # @return [Array] list of classes
-    def self.in_plans
+    def self.items
       arr = YARD::Registry.all(:puppet_plan).sort_by!(&:name).map!(&:to_hash)
       arr.map! { |a| PuppetStrings::Markdown::PuppetPlan.new(a) }
     end
-
-    def self.contains_private?
-      result = false
-      unless in_plans.nil?
-        in_plans.find { |plan| plan.private? }.nil? ? false : true
-      end
-    end
-
-    def self.render
-      final = in_plans.length > 0 ? "## Plans\n\n" : ""
-      in_plans.each do |plan|
-        final += plan.render unless plan.private?
-      end
-      final
-    end
-
-    def self.toc_info
-      final = ["Plans"]
-
-      in_plans.each do |plan|
-        final.push(plan.toc_info)
-      end
-
-      final
-    end
   end
 end

lib/puppet-strings/markdown/puppet_tasks.rb

@@ -4,33 +4,14 @@
 
 module PuppetStrings::Markdown
   module PuppetTasks
+    def self.name
+      'Tasks'
+    end
 
     # @return [Array] list of classes
-    def self.in_tasks
+    def self.items
       arr = YARD::Registry.all(:puppet_task).sort_by!(&:name).map!(&:to_hash)
       arr.map! { |a| PuppetStrings::Markdown::PuppetTask.new(a) }
     end
-
-    def self.contains_private?
-      false
-    end
-
-    def self.render
-      final = in_tasks.length > 0 ? "## Tasks\n\n" : ""
-      in_tasks.each do |task|
-        final += task.render unless task.private?
-      end
-      final
-    end
-
-    def self.toc_info
-      final = ["Tasks"]
-
-      in_tasks.each do |task|
-        final.push(task.toc_info)
-      end
-
-      final
-    end
   end
 end

lib/puppet-strings/markdown/resource_types.rb

@@ -4,36 +4,14 @@
 
 module PuppetStrings::Markdown
   module ResourceTypes
+    def self.name
+      'Resource types'
+    end
 
     # @return [Array] list of resource types
-    def self.in_rtypes
+    def self.items
       arr = YARD::Registry.all(:puppet_type).sort_by!(&:name).map!(&:to_hash)
       arr.map! { |a| PuppetStrings::Markdown::ResourceType.new(a) }
     end
-
-    def self.contains_private?
-      result = false
-      unless in_rtypes.nil?
-        in_rtypes.find { |type| type.private? }.nil? ? false : true
-      end
-    end
-
-    def self.render
-      final = in_rtypes.length > 0 ? "## Resource types\n\n" : ""
-      in_rtypes.each do |type|
-        final += type.render unless type.private?
-      end
-      final
-    end
-
-    def self.toc_info
-      final = ["Resource types"]
-
-      in_rtypes.each do |type|
-        final.push(type.toc_info)
-      end
-
-      final
-    end
   end
 end

lib/puppet-strings/markdown/table_of_contents.rb

@@ -3,24 +3,17 @@
 module PuppetStrings::Markdown
   module TableOfContents
     def self.render
-      final = "## Table of Contents\n\n"
+      template = PuppetStrings::Markdown.erb(File.join(__dir__, 'templates', 'table_of_contents.erb'))
+      renders = PuppetStrings::Markdown.groups.map do |group|
+        group_name = group.name
+        items = group.items.map { |item| item.toc_info }
+        has_private = items.any? { |item| item[:private] }
+        has_public = items.any? { |item| !item[:private] }
 
-      [PuppetStrings::Markdown::PuppetClasses,
-      PuppetStrings::Markdown::DefinedTypes,
-      PuppetStrings::Markdown::ResourceTypes,
-      PuppetStrings::Markdown::Functions,
-      PuppetStrings::Markdown::DataTypes,
-      PuppetStrings::Markdown::PuppetTasks,
-      PuppetStrings::Markdown::PuppetPlans].each do |r|
-        toc = r.toc_info
-        group_name = toc.shift
-        group = toc
-        priv = r.contains_private?
-
-        template = File.join(File.dirname(__FILE__), 'templates/table_of_contents.erb')
-        final += PuppetStrings::Markdown.erb(template).result(binding)
+        template.result(binding)
       end
-      final
+
+      "## Table of Contents\n\n" + renders.join('')
     end
   end
 end