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

Author: danielparks

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

lib/puppet-strings/markdown/base.rb

@@ -199,17 +199,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

lib/puppet-strings/markdown/data_types.rb

@@ -3,41 +3,19 @@
 require_relative 'data_type'
 
 module PuppetStrings::Markdown
+  # 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?
-      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

@@ -3,37 +3,16 @@
 require_relative 'defined_type'
 
 module PuppetStrings::Markdown
+  # 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?
-      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

@@ -3,38 +3,17 @@
 require_relative 'function'
 
 module PuppetStrings::Markdown
+  # 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?
-      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

@@ -3,37 +3,16 @@
 require_relative 'puppet_class'
 
 module PuppetStrings::Markdown
+  # 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?
-      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

@@ -3,37 +3,16 @@
 require_relative 'puppet_plan'
 
 module PuppetStrings::Markdown
+  # 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?
-      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

@@ -3,34 +3,16 @@
 require_relative 'puppet_task'
 
 module PuppetStrings::Markdown
+  # 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.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