(#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.

Author: danielparks

Diff for: lib/puppet-strings/markdown.rb

@@ -11,23 +11,52 @@ module PuppetStrings::Markdown
   require_relative 'markdown/resource_types'
   require_relative 'markdown/puppet_tasks'
   require_relative 'markdown/puppet_plans'
-  require_relative 'markdown/table_of_contents'
+
+  # Get modules that handle collecting and rendering each section.
+  #
+  # @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
+    output = [
+      "# Reference\n\n",
+      "<!-- DO NOT EDIT: This document was generated by Puppet Strings -->\n\n",
+      "## Table of Contents\n\n",
+    ]
+
+    # Create table of contents
+    template = erb(File.join(__dir__, 'markdown', 'templates', 'table_of_contents.erb'))
+    groups.each 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] }
+
+      output << template.result(binding)
+    end
+
+    # Create actual contents
+    groups.each do |group|
+      items = group.items.reject { |item| item.private? }
+      unless items.empty?
+        output << "## #{group.name}\n\n"
+        output.append(items.map { |item| item.render })
+      end
+    end
+
+    output.join('')
   end
 
   # mimicks the behavior of the json render, although path will never be nil
@@ -41,4 +70,17 @@ def self.render(path = nil)
       YARD::Logger.instance.debug "Wrote markdown to #{path}"
     end
   end
+
+  # Helper function to load an ERB template.
+  #
+  # @param [String] path The full path to the template file.
+  # @return [ERB] Template
+  def self.erb(path)
+    if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('2.6.0')
+      ERB.new(File.read(path), trim_mode: '-')
+    else
+      # This outputs warnings in Ruby 2.6+.
+      ERB.new(File.read(path), nil, '-')
+    end
+  end
 end

Diff for: lib/puppet-strings/markdown/base.rb

@@ -200,17 +200,4 @@ def clean_link(input)
       input.tr('^a-zA-Z0-9_-', '-')
     end
   end
-
-  # Helper function to load an ERB template.
-  #
-  # @param [String] path The full path to the template file.
-  # @return [ERB] Template
-  def self.erb(path)
-    if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('2.6.0')
-      ERB.new(File.read(path), trim_mode: '-')
-    else
-      # This outputs warnings in Ruby 2.6+.
-      ERB.new(File.read(path), nil, '-')
-    end
-  end
 end

Diff for: lib/puppet-strings/markdown/data_types.rb

@@ -3,38 +3,19 @@
 require_relative 'data_type'
 
 module PuppetStrings::Markdown
-  # Generates Markdown for Puppet Data Types.
+  # Adapter to get information about data types
   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?
-      return if in_dtypes.nil?
-      in_dtypes.find { |type| type.private? }.nil? ? false : true
-    end
-
-    def self.render
-      final = !in_dtypes.empty? ? "## 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

Diff for: lib/puppet-strings/markdown/defined_types.rb

@@ -3,35 +3,16 @@
 require_relative 'defined_type'
 
 module PuppetStrings::Markdown
-  # Generates Markdown for Puppet Defined Types.
+  # Adapter to get information about defined types
   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?
-      return if in_dtypes.nil?
-      in_dtypes.find { |type| type.private? }.nil? ? false : true
-    end
-
-    def self.render
-      final = !in_dtypes.empty? ? "## 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

Diff for: lib/puppet-strings/markdown/functions.rb

@@ -3,35 +3,16 @@
 require_relative 'function'
 
 module PuppetStrings::Markdown
-  # Generates Markdown for Puppet Functions.
+  # Adapter to get information about functions
   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?
-      return if in_functions.nil?
-      in_functions.find { |func| func.private? }.nil? ? false : true
-    end
-
-    def self.render
-      final = !in_functions.empty? ? "## 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

Diff for: lib/puppet-strings/markdown/puppet_classes.rb

@@ -3,35 +3,16 @@
 require_relative 'puppet_class'
 
 module PuppetStrings::Markdown
-  # Generates Markdown for Puppet Classes.
+  # Adapter to get information about classes
   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?
-      return if in_classes.nil?
-      in_classes.find { |klass| klass.private? }.nil? ? false : true
-    end
-
-    def self.render
-      final = !in_classes.empty? ? "## 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

Diff for: lib/puppet-strings/markdown/puppet_plans.rb

@@ -3,35 +3,16 @@
 require_relative 'puppet_plan'
 
 module PuppetStrings::Markdown
-  # Generates Markdown for Puppet Plans.
+  # Adapter to get information about plans
   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?
-      return if in_plans.nil?
-      in_plans.find { |plan| plan.private? }.nil? ? false : true
-    end
-
-    def self.render
-      final = !in_plans.empty? ? "## 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

Diff for: lib/puppet-strings/markdown/puppet_tasks.rb

@@ -3,34 +3,16 @@
 require_relative 'puppet_task'
 
 module PuppetStrings::Markdown
-  # Generates Markdown for Puppet Tasks.
+  # Adapter to get information about tasks
   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.empty? ? "## 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

Diff for: lib/puppet-strings/markdown/resource_types.rb

@@ -3,35 +3,16 @@
 require_relative 'resource_type'
 
 module PuppetStrings::Markdown
-  # Generates Markdown for Puppet Resource Types.
+  # Adapter to get information about resource types
   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?
-      return if in_rtypes.nil?
-      in_rtypes.find { |type| type.private? }.nil? ? false : true
-    end
-
-    def self.render
-      final = !in_rtypes.empty? ? "## 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