(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

@@ -4,30 +4,59 @@
 
 # module for parsing Yard Registries and generating markdown
 module PuppetStrings::Markdown
-  require_relative 'markdown/puppet_classes'
-  require_relative 'markdown/functions'
-  require_relative 'markdown/defined_types'
-  require_relative 'markdown/data_types'
-  require_relative 'markdown/resource_types'
-  require_relative 'markdown/puppet_tasks'
-  require_relative 'markdown/puppet_plans'
-  require_relative 'markdown/table_of_contents'
+  require_relative 'markdown/puppet_class'
+  require_relative 'markdown/function'
+  require_relative 'markdown/defined_type'
+  require_relative 'markdown/data_type'
+  require_relative 'markdown/resource_type'
+  require_relative 'markdown/puppet_task'
+  require_relative 'markdown/puppet_plan'
+
+  # Get classes that handle collecting and rendering each section/group.
+  #
+  # @return [Array[class]] The classes
+  def self.groups
+    [
+      PuppetStrings::Markdown::PuppetClass,
+      PuppetStrings::Markdown::DefinedType,
+      PuppetStrings::Markdown::ResourceType,
+      PuppetStrings::Markdown::Function,
+      PuppetStrings::Markdown::DataType,
+      PuppetStrings::Markdown::PuppetTask,
+      PuppetStrings::Markdown::PuppetPlan,
+    ]
+  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.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.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

@@ -50,6 +50,33 @@ module PuppetStrings::Markdown
   #  ") inherits foo::bar {\n" +
   #  "}"}
   class Base
+    # Set or return the name of the group
+    #
+    # @param [Optional[String]] Name of the group to set
+    # @return [String] Name of the group
+    def self.group_name(name = nil)
+      @group_name = name if name
+      @group_name
+    end
+
+    # Set or return the types registered with YARD
+    #
+    # @param [Optional[Array[Symbol]]] Array of symbols registered with YARD to set
+    # @return [Array[Symbol]] Array of symbols registered with YARD
+    def self.yard_types(types = nil)
+      @yard_types = types if types
+      @yard_types
+    end
+
+    # @return [Array] list of items
+    def self.items
+      yard_types
+        .flat_map { |type| YARD::Registry.all(type) }
+        .sort_by(&:name)
+        .map(&:to_hash)
+        .map { |i| new(i) }
+    end
+
     def initialize(registry, component_type)
       @type = component_type
       @registry = registry
@@ -200,17 +227,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_type.rb

@@ -8,6 +8,9 @@ class DataType < Base
     attr_reader :alias_of
     attr_reader :functions
 
+    group_name 'Data types'
+    yard_types [:puppet_data_type, :puppet_data_type_alias]
+
     def initialize(registry)
       @template = 'data_type.erb'
       super(registry, 'data type')

lib/puppet-strings/markdown/data_types.rb

@@ -5,6 +5,9 @@
 module PuppetStrings::Markdown
   # Generates Markdown for a Puppet Defined Type.
   class DefinedType < Base
+    group_name 'Defined types'
+    yard_types [:puppet_defined_type]
+
     def initialize(registry)
       @template = 'classes_and_defines.erb'
       super(registry, 'defined type')

lib/puppet-strings/markdown/defined_type.rb

@@ -7,6 +7,9 @@ module PuppetStrings::Markdown
   class Function < Base
     attr_reader :signatures
 
+    group_name 'Functions'
+    yard_types [:puppet_function]
+
     def initialize(registry)
       @template = 'function.erb'
       super(registry, 'function')

lib/puppet-strings/markdown/defined_types.rb

@@ -5,6 +5,9 @@
 module PuppetStrings::Markdown
   # Generates Markdown for a Puppet Class.
   class PuppetClass < Base
+    group_name 'Classes'
+    yard_types [:puppet_class]
+
     def initialize(registry)
       @template = 'classes_and_defines.erb'
       super(registry, 'class')

lib/puppet-strings/markdown/function.rb

@@ -5,6 +5,9 @@
 module PuppetStrings::Markdown
   # Generates Markdown for a Puppet Plan.
   class PuppetPlan < Base
+    group_name 'Plans'
+    yard_types [:puppet_plan]
+
     def initialize(registry)
       @template = 'classes_and_defines.erb'
       super(registry, 'plan')