From 6923d9e18cdb52c77c8d9378509b9889472c26a5 Mon Sep 17 00:00:00 2001 From: Eric Putnam Date: Mon, 26 Feb 2018 13:06:13 -0800 Subject: [PATCH] (maint) update table of contents The table_of_contents template was already too bulky and redundant and recognizing public and private components was only going to make it worse. This refactors the toc template and the toc class to use a generic outline for all components. --- lib/puppet-strings/markdown/base.rb | 12 ++++++- lib/puppet-strings/markdown/defined_types.rb | 17 +++++++--- lib/puppet-strings/markdown/functions.rb | 17 +++++++--- lib/puppet-strings/markdown/puppet_classes.rb | 17 +++++++--- lib/puppet-strings/markdown/resource_types.rb | 17 +++++++--- .../markdown/table_of_contents.rb | 20 ++++++++---- .../markdown/templates/table_of_contents.erb | 31 +++++++++---------- spec/fixtures/unit/markdown/output.md | 15 ++------- .../unit/puppet-strings/markdown/base_spec.rb | 6 ++++ spec/unit/puppet-strings/markdown_spec.rb | 3 +- 10 files changed, 97 insertions(+), 58 deletions(-) diff --git a/lib/puppet-strings/markdown/base.rb b/lib/puppet-strings/markdown/base.rb index ff3cedd..cb43c6b 100644 --- a/lib/puppet-strings/markdown/base.rb +++ b/lib/puppet-strings/markdown/base.rb @@ -130,7 +130,8 @@ module PuppetStrings::Markdown { name: name.to_s, link: link, - desc: summary || @registry[:docstring][:text].gsub("\n", ". ") + desc: summary || @registry[:docstring][:text].gsub("\n", ". "), + private: private? } end @@ -152,6 +153,15 @@ module PuppetStrings::Markdown end end + def private? + result = false + api = @tags.find { |tag| tag[:tag_name] == 'api' } + unless api.nil? + result = api[:text] == 'private' ? true : false + end + result + end + def contains_displayed_tags? result = @registry[:docstring][:text] ? true : false @tags.each do |tag| diff --git a/lib/puppet-strings/markdown/defined_types.rb b/lib/puppet-strings/markdown/defined_types.rb index fc26eb4..c10517f 100644 --- a/lib/puppet-strings/markdown/defined_types.rb +++ b/lib/puppet-strings/markdown/defined_types.rb @@ -5,23 +5,30 @@ module PuppetStrings::Markdown # @return [Array] list of defined types def self.in_dtypes - YARD::Registry.all(:puppet_defined_type).sort_by!(&:name).map!(&:to_hash) + 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| - to_render = PuppetStrings::Markdown::DefinedType.new(type) - final << to_render.render if to_render.contains_displayed_tags? + final << type.render unless type.private? end final end def self.toc_info - final = [] + final = ["Defined types"] in_dtypes.each do |type| - final.push(PuppetStrings::Markdown::DefinedType.new(type).toc_info) + final.push(type.toc_info) end final diff --git a/lib/puppet-strings/markdown/functions.rb b/lib/puppet-strings/markdown/functions.rb index c348318..f1cfb26 100644 --- a/lib/puppet-strings/markdown/functions.rb +++ b/lib/puppet-strings/markdown/functions.rb @@ -5,23 +5,30 @@ module PuppetStrings::Markdown # @return [Array] list of functions def self.in_functions - YARD::Registry.all(:puppet_function).sort_by!(&:name).map!(&:to_hash) + 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| - to_render = PuppetStrings::Markdown::Function.new(func) - final << to_render.render if to_render.contains_displayed_tags? + final << func.render unless func.private? end final end def self.toc_info - final = [] + final = ["Functions"] in_functions.each do |func| - final.push(PuppetStrings::Markdown::Function.new(func).toc_info) + final.push(func.toc_info) end final diff --git a/lib/puppet-strings/markdown/puppet_classes.rb b/lib/puppet-strings/markdown/puppet_classes.rb index dbef9af..625e7e2 100644 --- a/lib/puppet-strings/markdown/puppet_classes.rb +++ b/lib/puppet-strings/markdown/puppet_classes.rb @@ -5,23 +5,30 @@ module PuppetStrings::Markdown # @return [Array] list of classes def self.in_classes - YARD::Registry.all(:puppet_class).sort_by!(&:name).map!(&:to_hash) + 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| - to_render = PuppetStrings::Markdown::PuppetClass.new(klass) - final << to_render.render if to_render.contains_displayed_tags? + final << klass.render unless klass.private? end final end def self.toc_info - final = [] + final = ["Classes"] in_classes.each do |klass| - final.push(PuppetStrings::Markdown::PuppetClass.new(klass).toc_info) + final.push(klass.toc_info) end final diff --git a/lib/puppet-strings/markdown/resource_types.rb b/lib/puppet-strings/markdown/resource_types.rb index 76e7777..3f48765 100644 --- a/lib/puppet-strings/markdown/resource_types.rb +++ b/lib/puppet-strings/markdown/resource_types.rb @@ -5,23 +5,30 @@ module PuppetStrings::Markdown # @return [Array] list of resource types def self.in_rtypes - YARD::Registry.all(:puppet_type).sort_by!(&:name).map!(&:to_hash) + 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| - to_render = PuppetStrings::Markdown::ResourceType.new(type) - final << to_render.render if to_render.contains_displayed_tags? + final << type.render unless type.private? end final end def self.toc_info - final = [] + final = ["Resource types"] in_rtypes.each do |type| - final.push(PuppetStrings::Markdown::ResourceType.new(type).toc_info) + final.push(type.toc_info) end final diff --git a/lib/puppet-strings/markdown/table_of_contents.rb b/lib/puppet-strings/markdown/table_of_contents.rb index 3afa119..ed230ac 100644 --- a/lib/puppet-strings/markdown/table_of_contents.rb +++ b/lib/puppet-strings/markdown/table_of_contents.rb @@ -1,13 +1,21 @@ module PuppetStrings::Markdown module TableOfContents def self.render - puppet_classes = PuppetStrings::Markdown::PuppetClasses.toc_info - puppet_defined_types = PuppetStrings::Markdown::DefinedTypes.toc_info - puppet_resource_types = PuppetStrings::Markdown::ResourceTypes.toc_info - puppet_functions = PuppetStrings::Markdown::Functions.toc_info + final = "" - template = File.join(File.dirname(__FILE__),"templates/table_of_contents.erb") - ERB.new(File.read(template), nil, '-').result(binding) + [PuppetStrings::Markdown::PuppetClasses, + PuppetStrings::Markdown::DefinedTypes, + PuppetStrings::Markdown::ResourceTypes, + PuppetStrings::Markdown::Functions].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 << ERB.new(File.read(template), nil, '-').result(binding) + end + final end end end diff --git a/lib/puppet-strings/markdown/templates/table_of_contents.erb b/lib/puppet-strings/markdown/templates/table_of_contents.erb index d726b5e..c2b4e18 100644 --- a/lib/puppet-strings/markdown/templates/table_of_contents.erb +++ b/lib/puppet-strings/markdown/templates/table_of_contents.erb @@ -1,24 +1,21 @@ -<% if puppet_classes.length > 0 -%> -## Classes -<% puppet_classes.each do |klassy| -%> -* [`<%= klassy[:name] %>`](#<%= klassy[:link] %>): <%= klassy[:desc] %> +<% if group.length > 0 -%> +## <%= group_name %> +<% if priv -%> +### Public <%= group_name %> +<% group.each do |item| -%> +<% unless item[:private] -%> +* [`<%= item[:name] %>`](#<%= item[:link] %>): <%= item[:desc] %> <% end -%> <% end -%> -<% if puppet_defined_types.length > 0 -%> -## Defined types -<% puppet_defined_types.each do |dtype| -%> -* [`<%= dtype[:name] %>`](#<%= dtype[:link] %>): <%= dtype[:desc] %> +### Private <%= group_name %> +<% group.each do |item| -%> +<% if item[:private] -%> +* `<%= item[:name] %>`: <%= item[:desc] %> <% end -%> <% end -%> -<% if puppet_resource_types.length > 0 -%> -## Resource types -<% puppet_resource_types.each do |rtype| -%> -* [`<%= rtype[:name] %>`](#<%= rtype[:link] %>): <%= rtype[:desc] %> +<% else -%> +<% group.each do |item| -%> +* [`<%= item[:name] %>`](#<%= item[:link] %>): <%= item[:desc] %> <% end -%> <% end -%> -<% if puppet_functions.length > 0 -%> -## Functions -<% puppet_functions.each do |func| -%> -* [`<%= func[:name] %>`](#<%= func[:link] %>): <%= func[:desc] %> -<% end -%> <% end -%> diff --git a/spec/fixtures/unit/markdown/output.md b/spec/fixtures/unit/markdown/output.md index 594f149..9d225c8 100644 --- a/spec/fixtures/unit/markdown/output.md +++ b/spec/fixtures/unit/markdown/output.md @@ -1,9 +1,10 @@ # Reference ## Classes +### Public Classes * [`klass`](#klass): A simple class. -* [`noparams`](#noparams): Overview for class noparams -* [`noparams_desc`](#noparams_desc): +### Private Classes +* `noparams`: Overview for class noparams ## Defined types * [`klass::dt`](#klassdt): A simple defined type. ## Resource types @@ -78,16 +79,6 @@ Third param. Default value: 'hi' -### noparams - -Overview for class noparams - - -### noparams_desc - -The noparams_desc class. - - ## Defined types ### klass::dt diff --git a/spec/unit/puppet-strings/markdown/base_spec.rb b/spec/unit/puppet-strings/markdown/base_spec.rb index 6713f2a..fa254eb 100644 --- a/spec/unit/puppet-strings/markdown/base_spec.rb +++ b/spec/unit/puppet-strings/markdown/base_spec.rb @@ -114,6 +114,12 @@ SOURCE end end + describe '#private?' do + it do + expect(component.private?).to be false + end + end + describe '#toc_info' do let(:toc) { component.toc_info } it 'returns a hash' do diff --git a/spec/unit/puppet-strings/markdown_spec.rb b/spec/unit/puppet-strings/markdown_spec.rb index 98d0ab1..8c0c052 100644 --- a/spec/unit/puppet-strings/markdown_spec.rb +++ b/spec/unit/puppet-strings/markdown_spec.rb @@ -36,10 +36,9 @@ class klass ( } # Overview for class noparams +# @api private class noparams () {} -class noparams_desc () {} - # An overview for a simple defined type. # @summary A simple defined type. # @since 1.1.0