Merge pull request #314 from danielparks/better_public_private

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

Author: chelnak

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')