puppet-strings 2.5.0 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 543437ac3fd3177245de47e563235b3f99194299f1c1cf14132bed3850de5056
-  data.tar.gz: 4aaa21554b916ca541ae3ce04a21ab34912375499347a816292858915aa803cf
+  metadata.gz: 9aa1aa13861fd95a237ca2abd1ef890dfbcba1b7757c2dd609d648b803df7a33
+  data.tar.gz: 55d8b1903917fcd24fbb53dbe1433449a75eb88544071fdf0e2bf2d0eeb2fe11
 SHA512:
-  metadata.gz: c73e04ec0c084f0000751eaa618ed5daa0efcfebf101e1d63832ab46403d0eff01ab628c028eae368097d2b3500c2e869d292c0fa07ad4eb68392773125b3ddf
-  data.tar.gz: 2a40adbd4874289129cecca5164f65ce3021a83a7cc3559bd6a6b28e3154020e1a9cd5a076c119827072feb47e2f6fe562924cfd63158f4c3e924ba132e0ddcd
+  metadata.gz: 394ad674391503b4a894857035fbe190678bba4b264d6093935005b22322beda448fb38470ba92acedb191e1faec8dab01ccd0cc14ba807ca5b39cc6bff6b2fc
+  data.tar.gz: 420511c57607c8d76eb2d3e8b6417a84d3ac4247c3fc64ddd83a23fa50aba570b1e984e1a67a3c56c929c4ac8aeebf84726cd14e39ad689405ee8726281ae1dd

data/CHANGELOG.md

@@ -3,14 +3,39 @@
 All significant changes to this repo will be summarized in this file.
 
 
-## [v2.5.0](https://github.com/puppetlabs/puppet-strings/tree/v2.5.0) (2020-07-15)
+## [v2.6.0](https://github.com/puppetlabs/puppet-strings/tree/v2.6.0) (2021-01-18)
+
+[Full Changelog](https://github.com/puppetlabs/puppet-strings/compare/v2.5.0...v2.6.0)
+
+Added
+
+- Improved markdown templates [\#252](https://github.com/puppetlabs/puppet-strings/pull/252) ([kozl](https://github.com/kozl))
+
+Fixed
+
+- Do not fail in case return tag has no type specified [\#268](https://github.com/puppetlabs/puppet-strings/pull/268) ([tiandrey](https://github.com/tiandrey))
+- Handle a missing description gracefully [\#260](https://github.com/puppetlabs/puppet-strings/pull/260) ([scotje](https://github.com/scotje))
+- Fix ERB failure - parameters without descriptions [\#255](https://github.com/puppetlabs/puppet-strings/pull/255) ([trevor-vaughan](https://github.com/trevor-vaughan))
+- puppet\_function template: fix tags, source [\#249](https://github.com/puppetlabs/puppet-strings/pull/249) ([raemer](https://github.com/raemer))
+
+Changed
+
+- \(MAINT\) Drop Ruby 2.1.x and Puppet 4.x compatibility [\#253](https://github.com/puppetlabs/puppet-strings/pull/253) ([scotje](https://github.com/scotje))
+
+**Closed issues:**
+
+- Tags \(Parameter, Returns\) not generated in HTML output [\#248](https://github.com/puppetlabs/puppet-strings/issues/248)
+- Can we get 2.5.0 released please [\#244](https://github.com/puppetlabs/puppet-strings/issues/244)
+- Add supported\_features to puppet strings input/output for types [\#228](https://github.com/puppetlabs/puppet-strings/issues/228)
+- Provider attribute is missing in generated types documentation [\#227](https://github.com/puppetlabs/puppet-strings/issues/227)
+
+## [v2.5.0](https://github.com/puppetlabs/puppet-strings/tree/v2.5.0) (2020-07-16)
 
 [Full Changelog](https://github.com/puppetlabs/puppet-strings/compare/v2.4.0...v2.5.0)
 
 Added
 
 - \(GH-225\) Document functions in Puppet Datatypes [\#235](https://github.com/puppetlabs/puppet-strings/pull/235) ([glennsarti](https://github.com/glennsarti))
-- Add checks to resource\_type handler and code objects [\#232](https://github.com/puppetlabs/puppet-strings/pull/232) ([scotje](https://github.com/scotje))
 - \(\#227\) Inject `provider` into params list for types with providers [\#231](https://github.com/puppetlabs/puppet-strings/pull/231) ([scotje](https://github.com/scotje))
 
 Fixed
@@ -27,12 +52,17 @@ Fixed
 - Document usage [\#8](https://github.com/puppetlabs/puppet-strings/issues/8)
 - Need a search box on the main page [\#1](https://github.com/puppetlabs/puppet-strings/issues/1)
 
+**Merged pull requests:**
+
+- Release prep for v2.5.0 [\#245](https://github.com/puppetlabs/puppet-strings/pull/245) ([scotje](https://github.com/scotje))
+
 ## [v2.4.0](https://github.com/puppetlabs/puppet-strings/tree/v2.4.0) (2020-02-20)
 
 [Full Changelog](https://github.com/puppetlabs/puppet-strings/compare/v2.3.1...v2.4.0)
 
 Added
 
+- Add checks to resource\_type handler and code objects [\#232](https://github.com/puppetlabs/puppet-strings/pull/232) ([scotje](https://github.com/scotje))
 - Add missing HTML output support for enum tag [\#218](https://github.com/puppetlabs/puppet-strings/pull/218) ([seanmil](https://github.com/seanmil))
 - \(PDOC-295\) Add @enum tag support for Enum data types [\#215](https://github.com/puppetlabs/puppet-strings/pull/215) ([seanmil](https://github.com/seanmil))
 - Expanded default search glob for plans. [\#214](https://github.com/puppetlabs/puppet-strings/pull/214) ([Raskil](https://github.com/Raskil))
@@ -58,10 +88,6 @@ Added
 
 - Add Puppet Data Type documentation [\#199](https://github.com/puppetlabs/puppet-strings/pull/199) ([glennsarti](https://github.com/glennsarti))
 
-Fixed
-
-- \(PDOC-283\) Fix namespaced symbols [\#205](https://github.com/puppetlabs/puppet-strings/pull/205) ([glennsarti](https://github.com/glennsarti))
-
 ## [v2.2.0](https://github.com/puppetlabs/puppet-strings/tree/v2.2.0) (2019-04-05)
 
 [Full Changelog](https://github.com/puppetlabs/puppet-strings/compare/v2.1.0...v2.2.0)
@@ -75,6 +101,7 @@ Added
 
 Fixed
 
+- \(PDOC-283\) Fix namespaced symbols [\#205](https://github.com/puppetlabs/puppet-strings/pull/205) ([glennsarti](https://github.com/glennsarti))
 - \(PDOC-266\) Silence 'unexpected construct regexp\_literal' warning [\#189](https://github.com/puppetlabs/puppet-strings/pull/189) ([seanmil](https://github.com/seanmil))
 
 ## [v2.1.0](https://github.com/puppetlabs/puppet-strings/tree/v2.1.0) (2018-06-26)

data/lib/puppet-strings.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # The root module for Puppet Strings.
 module PuppetStrings
   # The glob patterns used to search for files to document.

data/lib/puppet-strings/describe.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'json'
 require 'puppet-strings/json'
 

data/lib/puppet-strings/json.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'json'
 
 # The module for JSON related functionality.

data/lib/puppet-strings/markdown.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/json'
 
 # module for parsing Yard Registries and generating markdown
@@ -15,15 +17,15 @@ module PuppetStrings::Markdown
   # @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 += "<!-- 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
   end

data/lib/puppet-strings/markdown/base.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings'
 require 'puppet-strings/json'
 require 'puppet-strings/yard'
@@ -68,7 +70,7 @@ module PuppetStrings::Markdown
 
     # @return [String] top-level name
     def name
-      @registry[:name].to_s unless @registry[:name].nil?
+      @registry[:name]&.to_s
     end
 
     # @return [String] 'Overview' text (untagged text)
@@ -170,6 +172,8 @@ module PuppetStrings::Markdown
     end
 
     def word_wrap(text, line_width: 120, break_sequence: "\n")
+      return unless text
+
       text.split("\n").collect! do |line|
         line.length > line_width ? line.gsub(/(.{1,#{line_width}})(\s+|$)/, "\\1#{break_sequence}").strip : line
       end * break_sequence
@@ -177,8 +181,12 @@ module PuppetStrings::Markdown
 
     # @return [String] full markdown rendering of a component
     def render(template)
-      file = File.join(File.dirname(__FILE__),"templates/#{template}")
-      ERB.new(File.read(file), nil, '-').result(binding)
+      begin
+        file = File.join(File.dirname(__FILE__),"templates/#{template}")
+        ERB.new(File.read(file), nil, '-').result(binding)
+      rescue StandardError => e
+        fail "Processing #{@registry[:file]}:#{@registry[:line]} with #{file} => #{e}"
+      end
     end
 
     private

data/lib/puppet-strings/markdown/data_type.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/markdown/base'
 
 module PuppetStrings::Markdown

data/lib/puppet-strings/markdown/data_types.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative 'data_type'
 
 module PuppetStrings::Markdown
@@ -22,7 +24,7 @@ module PuppetStrings::Markdown
     def self.render
       final = in_dtypes.length > 0 ? "## Data types\n\n" : ""
       in_dtypes.each do |type|
-        final << type.render unless type.private?
+        final += type.render unless type.private?
       end
       final
     end

data/lib/puppet-strings/markdown/defined_type.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/markdown/base'
 
 module PuppetStrings::Markdown

data/lib/puppet-strings/markdown/defined_types.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative 'defined_type'
 
 module PuppetStrings::Markdown
@@ -19,7 +21,7 @@ module PuppetStrings::Markdown
     def self.render
       final = in_dtypes.length > 0 ? "## Defined types\n\n" : ""
       in_dtypes.each do |type|
-        final << type.render unless type.private?
+        final += type.render unless type.private?
       end
       final
     end

data/lib/puppet-strings/markdown/function.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/markdown/base'
 
 module PuppetStrings::Markdown
@@ -19,23 +21,23 @@ module PuppetStrings::Markdown
 
     def type
       t = @registry[:type]
-      if t =~ /ruby4x/
+      if /ruby4x/.match?(t)
         "Ruby 4.x API"
-      elsif t =~ /ruby3/
+      elsif /ruby3/.match?(t)
         "Ruby 3.x API"
-      elsif t =~ /ruby/
+      elsif /ruby/.match?(t)
         "Ruby"
       else
         "Puppet Language"
       end
     end
 
-    def error_type(r) # rubocop:disable Naming/UncommunicativeMethodParamName
-      "`#{r.split(' ')[0]}`"
+    def error_type(type)
+      "`#{type.split(' ')[0]}`"
     end
 
-    def error_text(r) # rubocop:disable Naming/UncommunicativeMethodParamName
-      "#{r.split(' ').drop(1).join(' ')}"
+    def error_text(text)
+      "#{text.split(' ').drop(1).join(' ')}"
     end
   end
 

data/lib/puppet-strings/markdown/functions.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative 'function'
 
 module PuppetStrings::Markdown
@@ -19,7 +21,7 @@ module PuppetStrings::Markdown
     def self.render
       final = in_functions.length > 0 ? "## Functions\n\n" : ""
       in_functions.each do |func|
-        final << func.render unless func.private?
+        final += func.render unless func.private?
       end
       final
     end

data/lib/puppet-strings/markdown/puppet_class.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/markdown/base'
 
 module PuppetStrings::Markdown

data/lib/puppet-strings/markdown/puppet_classes.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative 'puppet_class'
 
 module PuppetStrings::Markdown
@@ -19,7 +21,7 @@ module PuppetStrings::Markdown
     def self.render
       final = in_classes.length > 0 ? "## Classes\n\n" : ""
       in_classes.each do |klass|
-        final << klass.render unless klass.private?
+        final += klass.render unless klass.private?
       end
       final
     end

data/lib/puppet-strings/markdown/puppet_plan.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/markdown/base'
 
 module PuppetStrings::Markdown

data/lib/puppet-strings/markdown/puppet_plans.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative 'puppet_plan'
 
 module PuppetStrings::Markdown
@@ -19,7 +21,7 @@ module PuppetStrings::Markdown
     def self.render
       final = in_plans.length > 0 ? "## Plans\n\n" : ""
       in_plans.each do |plan|
-        final << plan.render unless plan.private?
+        final += plan.render unless plan.private?
       end
       final
     end

data/lib/puppet-strings/markdown/puppet_task.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/markdown/base'
 
 module PuppetStrings::Markdown

data/lib/puppet-strings/markdown/puppet_tasks.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative 'puppet_task'
 
 module PuppetStrings::Markdown
@@ -16,7 +18,7 @@ module PuppetStrings::Markdown
     def self.render
       final = in_tasks.length > 0 ? "## Tasks\n\n" : ""
       in_tasks.each do |task|
-        final << task.render unless task.private?
+        final += task.render unless task.private?
       end
       final
     end

data/lib/puppet-strings/markdown/resource_type.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/markdown/base'
 
 module PuppetStrings::Markdown

data/lib/puppet-strings/markdown/resource_types.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative 'resource_type'
 
 module PuppetStrings::Markdown
@@ -19,7 +21,7 @@ module PuppetStrings::Markdown
     def self.render
       final = in_rtypes.length > 0 ? "## Resource types\n\n" : ""
       in_rtypes.each do |type|
-        final << type.render unless type.private?
+        final += type.render unless type.private?
       end
       final
     end

data/lib/puppet-strings/markdown/table_of_contents.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module PuppetStrings::Markdown
   module TableOfContents
     def self.render
@@ -16,7 +18,7 @@ module PuppetStrings::Markdown
         priv = r.contains_private?
 
         template = File.join(File.dirname(__FILE__),"templates/table_of_contents.erb")
-        final << ERB.new(File.read(template), nil, '-').result(binding)
+        final += ERB.new(File.read(template), nil, '-').result(binding)
       end
       final
     end

data/lib/puppet-strings/markdown/templates/classes_and_defines.erb

@@ -1,4 +1,4 @@
-### `<%= name %>`
+### <a name="<%= link %>"></a>`<%= name %>`
 
 <% if text -%>
 <%= text %>
@@ -47,10 +47,14 @@
 <% if params -%>
 #### Parameters
 
-The following parameters are available in the `<%= name %>` <%= @type %>.
+The following parameters are available in the `<%= name %>` <%= @type %>:
 
 <% params.each do |param| -%>
-##### `<%= param[:name] %>`
+* [`<%= param[:name] %>`](#<%= param[:name] %>)
+<% end -%>
+
+<% params.each do |param| -%>
+##### <a name="<%= param[:name] %>"></a>`<%= param[:name] %>`
 
 <% if param[:types] -%>
 Data type: `<%= param[:types].join(', ') -%>`

data/lib/puppet-strings/markdown/templates/data_type.erb

@@ -1,4 +1,4 @@
-### `<%= name %>`
+### <a name="<%= link %>"></a>`<%= name %>`
 
 <% if text -%>
 <%= text %>
@@ -45,16 +45,24 @@
 <% end -%>
 <% end -%>
 <% if alias_of -%>
-Alias of `<%= alias_of %>`
+Alias of
+
+```puppet
+<%= alias_of %>
+```
 
 <% end -%>
 <% if params -%>
 #### Parameters
 
-The following parameters are available in the `<%= name %>` <%= @type %>.
+The following parameters are available in the `<%= name %>` <%= @type %>:
+
+<% params.each do |param| -%>
+* [`<%= param[:name] %>`](#<%= param[:name] %>)
+<% end -%>
 
 <% params.each do |param| -%>
-##### `<%= param[:name] %>`
+##### <a name="<%= param[:name] %>"></a>`<%= param[:name] %>`
 
 <% if param[:types] -%>
 Data type: `<%= param[:types].join(', ') -%>`

data/lib/puppet-strings/markdown/templates/data_type_function.erb

@@ -1,4 +1,4 @@
-### `<%= name %>`
+### <a name="<%= link %>"></a>`<%= name %>`
 
 #### `<%= signature %>`
 

data/lib/puppet-strings/markdown/templates/function.erb

@@ -1,4 +1,4 @@
-### `<%= name %>`
+### <a name="<%= link %>"></a>`<%= name %>`
 
 Type: <%= type %>