puppet-strings 2.4.0 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9bfc095b6c7aa9124cfa44c79aa0404361fbe9b3971e58495aa8354f1b84163a
-  data.tar.gz: 56c425e69b8bd4b1e9c6a0bb07a25ca806d880e6e9a865afa8137d12b5412442
+  metadata.gz: 543437ac3fd3177245de47e563235b3f99194299f1c1cf14132bed3850de5056
+  data.tar.gz: 4aaa21554b916ca541ae3ce04a21ab34912375499347a816292858915aa803cf
 SHA512:
-  metadata.gz: 0a0fcbc8af4653fb35166cad42488f21bf5f046092ef1434331c7d4ba03fa4ac2544c3e220859c9dc2de94b4a263caed7b35a6185df297bf6dbb631553601f9d
-  data.tar.gz: 7cf9f63f1fd50af678f4b3891ed7ac9da3d5eda249de6df50dd10ac93eed078f1f7fab6b5ca6945e6e057e89ce55c227b4aba1aab84884e6d89b1f039677ed38
+  metadata.gz: c73e04ec0c084f0000751eaa618ed5daa0efcfebf101e1d63832ab46403d0eff01ab628c028eae368097d2b3500c2e869d292c0fa07ad4eb68392773125b3ddf
+  data.tar.gz: 2a40adbd4874289129cecca5164f65ce3021a83a7cc3559bd6a6b28e3154020e1a9cd5a076c119827072feb47e2f6fe562924cfd63158f4c3e924ba132e0ddcd

data/CHANGELOG.md

@@ -3,7 +3,31 @@
 All significant changes to this repo will be summarized in this file.
 
 
-## [v2.4.0](https://github.com/puppetlabs/puppet-strings/tree/v2.4.0) (2020-02-18)
+## [v2.5.0](https://github.com/puppetlabs/puppet-strings/tree/v2.5.0) (2020-07-15)
+
+[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
+
+- \(\#242\) Wrap names in backticks when rendering to markdown [\#243](https://github.com/puppetlabs/puppet-strings/pull/243) ([scotje](https://github.com/scotje))
+- Eliminate trailing spaces w/o descriptions [\#224](https://github.com/puppetlabs/puppet-strings/pull/224) ([binford2k](https://github.com/binford2k))
+
+**Closed issues:**
+
+- text rendering as emojis in strings generated docs [\#242](https://github.com/puppetlabs/puppet-strings/issues/242)
+- Puppet Classes not Listed in Left Frame Contents [\#241](https://github.com/puppetlabs/puppet-strings/issues/241)
+- exec type in generated docs missing attributes `creates`, `onlyif` [\#229](https://github.com/puppetlabs/puppet-strings/issues/229)
+- \[Feature\] Document functions in Puppet Datatypes [\#225](https://github.com/puppetlabs/puppet-strings/issues/225)
+- 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)
+
+## [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)
 
@@ -13,6 +37,10 @@ Added
 - \(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))
 
+**Merged pull requests:**
+
+- \(MAINT\) Release prep for 2.4.0 [\#221](https://github.com/puppetlabs/puppet-strings/pull/221) ([scotje](https://github.com/scotje))
+
 ## [v2.3.1](https://github.com/puppetlabs/puppet-strings/tree/v2.3.1) (2019-09-23)
 
 [Full Changelog](https://github.com/puppetlabs/puppet-strings/compare/v2.3.0...v2.3.1)
@@ -282,4 +310,4 @@ All related tickets can be found under the [PDOC][PDOC JIRA] JIRA project with t
 - Strings will no longer crash when documenting 3x functions with less than two arguments passed into newfunction **(PDOC-27)**
 
 
-\* *This Changelog was automatically generated by [github_changelog_generator](https://github.com/skywinder/Github-Changelog-Generator)*
+\* *This Changelog was automatically generated by [github_changelog_generator](https://github.com/github-changelog-generator/github-changelog-generator)*

data/lib/puppet-strings.rb

@@ -27,8 +27,9 @@ module PuppetStrings
 
     # Format the arguments to YARD
     args = ['doc']
+    args << '--no-progress'
     args << '--debug'     if options[:debug]
-    args << '--backtrace' if options[:backtrace]
+    args << '--backtrace' if options[:debug]
     args << "-m#{options[:markup] || 'markdown'}"
 
     file = nil
@@ -42,7 +43,6 @@ module PuppetStrings
       args << '-n'
       args << '-q' unless file
       args << '--no-stats' unless file
-      args << '--no-progress' unless file
     end
 
     yard_args = options[:yard_args]

data/lib/puppet-strings/markdown.rb

@@ -14,7 +14,7 @@ module PuppetStrings::Markdown
   # generates markdown documentation
   # @return [String] markdown doc
   def self.generate
-    final = "# Reference\n"
+    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

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

@@ -169,6 +169,12 @@ module PuppetStrings::Markdown
       @tags.any? { |tag| tag[:tag_name] == 'api' && tag[:text] == 'private' }
     end
 
+    def word_wrap(text, line_width: 120, break_sequence: "\n")
+      text.split("\n").collect! do |line|
+        line.length > line_width ? line.gsub(/(.{1,#{line_width}})(\s+|$)/, "\\1#{break_sequence}").strip : line
+      end * break_sequence
+    end
+
     # @return [String] full markdown rendering of a component
     def render(template)
       file = File.join(File.dirname(__FILE__),"templates/#{template}")

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

@@ -4,15 +4,31 @@ module PuppetStrings::Markdown
   # This class encapsualtes ruby data types and puppet type aliases
   class DataType < Base
     attr_reader :alias_of
+    attr_reader :functions
 
     def initialize(registry)
       @template = 'data_type.erb'
       super(registry, 'data type')
       @alias_of = registry[:alias_of] unless registry[:alias_of].nil?
+      @functions = @registry[:functions].nil? ? nil : @registry[:functions].map { |func| DataType::Function.new(func) }
     end
 
     def render
       super(@template)
     end
   end
+
+  class DataType::Function < Base
+    def initialize(registry)
+      super(registry, 'data_type_function')
+    end
+
+    def render
+      super('data_type_function.erb')
+    end
+
+    def signature
+      @registry[:signature]
+    end
+  end
 end

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

@@ -12,11 +12,28 @@ module PuppetStrings::Markdown
     end
 
     def properties
-      @registry[:properties]
+      return nil unless @registry[:properties]
+
+      @registry[:properties].sort_by { |p| p[:name] }
+    end
+
+    def checks
+      return nil unless @registry[:checks]
+
+      @registry[:checks].sort_by { |p| p[:name] }
+    end
+
+    # "checks" (such as "onlyif" or "creates") are another type of property
+    def properties_and_checks
+      return nil if properties.nil? && checks.nil?
+
+      ((properties || []) + (checks || [])).sort_by { |p| p[:name] }
     end
 
     def parameters
-      @registry[:parameters]
+      return nil unless @registry[:parameters]
+
+      @registry[:parameters].sort_by { |p| p[:name] }
     end
 
     def regex_in_data_type?(data_type)

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

@@ -1,4 +1,4 @@
-### <%= name %>
+### `<%= name %>`
 
 <% if text -%>
 <%= text %>
@@ -24,10 +24,10 @@
 * **See also**
 <% see.each do |sa| -%>
 <% if sa[:name] -%>
-<%= sa[:name] %>
+<%= "  * #{sa[:name]}" %>
 <% end -%>
 <% if sa[:text] -%>
-<%= sa[:text] %>
+  <%= "  * #{sa[:text]}" %>
 <% end -%>
 <% end -%>
 
@@ -75,7 +75,7 @@ Options:
 
 <% end -%>
 <% if defaults && defaults[param[:name]] -%>
-Default value: <%= value_string(defaults[param[:name]]) %>
+Default value: `<%= value_string(defaults[param[:name]]) %>`
 
 <% end -%>
 <% end -%>

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

@@ -1,4 +1,4 @@
-### <%= name %>
+### `<%= name %>`
 
 <% if text -%>
 <%= text %>
@@ -24,10 +24,10 @@
 * **See also**
 <% see.each do |sa| -%>
 <% if sa[:name] -%>
-<%= sa[:name] %>
+<%= "  * #{sa[:name]}" %>
 <% end -%>
 <% if sa[:text] -%>
-<%= sa[:text] %>
+<%= "  * #{sa[:text]}" %>
 <% end -%>
 <% end -%>
 
@@ -79,8 +79,15 @@ Options:
 
 <% end -%>
 <% if defaults && defaults[param[:name]] -%>
-Default value: <%= value_string(defaults[param[:name]]) %>
+Default value: `<%= value_string(defaults[param[:name]]) %>`
 
 <% end -%>
 <% end -%>
 <% end -%>
+<% if functions -%>
+#### Functions
+
+The following functions are available in the `<%= name %>` <%= @type %>.
+
+<% functions.each do |func| -%><%= func.render -%><% end -%>
+<% end -%>

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

@@ -0,0 +1,67 @@
+### `<%= name %>`
+
+#### `<%= signature %>`
+
+<% if text -%>
+<%= text %>
+
+<% elsif summary -%>
+<%= summary %>
+
+<% else -%>
+<%= "The #{name} function." %>
+
+<% end -%>
+<% if note -%>
+* **Note** <%= note %>
+
+<% end -%>
+<% if return_type -%>
+Returns: `<%= return_type %>`<% if return_val %> <%= return_val %><% end %>
+
+<% end -%>
+<% if raises -%>
+Raises:
+<% raises.each do |r| -%>
+* <%= error_type(r[:text]) %> <%= error_text(r[:text]) %>
+<% end -%>
+
+<% end -%>
+<% if examples -%>
+##### Examples
+
+<% examples.each do |eg| -%>
+###### <%= eg[:name] %>
+
+```puppet
+<%= eg[:text] %>
+```
+
+<% end -%>
+<% end -%>
+<% if params -%>
+<% params.each do |param| -%>
+##### `<%= param[:name]  %>`
+
+Data type: `<%= param[:types][0] %>`
+
+<%= param[:text] %>
+
+<% if options_for_param(param[:name]) -%>
+Options:
+
+<% options_for_param(param[:name]).each do |o| -%>
+* **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
+<% end -%>
+
+<% end -%>
+<% if enums_for_param(param[:name]) -%>
+Options:
+
+<% enums_for_param(param[:name]).each do |e| -%>
+* **<%= e[:opt_name] %>**: <%= e[:opt_text] %>
+<% end -%>
+
+<% end -%>
+<% end -%>
+<% end -%>

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

@@ -1,4 +1,4 @@
-### <%= name %>
+### `<%= name %>`
 
 Type: <%= type %>
 
@@ -55,6 +55,7 @@ Returns: `<%= sig.return_type %>`<% if sig.return_val %> <%= sig.return_val %><%
 <% end -%>
 <% if raises -%>
 Raises:
+
 <% raises.each do |r| -%>
 * <%= error_type(r[:text]) %> <%= error_text(r[:text]) %>
 <% end -%>

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

@@ -1,4 +1,4 @@
-### <%= name %>
+### `<%= name %>`
 
 <% if text -%>
 <%= text %>

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

@@ -1,4 +1,4 @@
-### <%= name %>
+### `<%= name %>`
 
 <% if text -%>
 <%= text %>
@@ -24,10 +24,10 @@
 * **See also**
 <% see.each do |sa| -%>
 <% if sa[:name] -%>
-<%= sa[:name] %>
+<%= "  * #{sa[:name]}" %>
 <% end -%>
 <% if sa[:text] -%>
-<%= sa[:text] %>
+<%= "  * #{sa[:text]}" %>
 <% end -%>
 <% end -%>
 
@@ -44,16 +44,16 @@
 
 <% end -%>
 <% end -%>
-<% if properties -%>
+<% if properties_and_checks -%>
 #### Properties
 
 The following properties are available in the `<%= name %>` <%= @type %>.
 
-<% properties.each do |prop| -%>
+<% properties_and_checks.each do |prop| -%>
 ##### `<%= prop[:name] %>`
 
 <% if prop[:values] -%>
-Valid values: <%= prop[:values].map { |value| value_string(value) }.join(', ') %>
+Valid values: `<%= prop[:values].map { |value| value_string(value) }.join('`, `') %>`
 
 <% end -%>
 <% if prop[:isnamevar] -%>
@@ -61,7 +61,7 @@ namevar
 
 <% end -%>
 <% if prop[:aliases] -%>
-Aliases: <%= prop[:aliases].to_s.delete('{').delete('}') %>
+Aliases: `<%= prop[:aliases].to_s.delete('{').delete('}') %>`
 
 <% end -%>
 <% if prop[:data_type] -%>
@@ -87,7 +87,7 @@ Options:
 
 <% end -%>
 <% if prop[:default] -%>
-Default value: <%= prop[:default] %>
+Default value: `<%= prop[:default] %>`
 
 <% end -%>
 <% end -%>
@@ -101,7 +101,7 @@ The following parameters are available in the `<%= name %>` <%= @type %>.
 ##### `<%= param[:name] %>`
 
 <% if param[:values] -%>
-Valid values: <%= param[:values].map { |value| value_string(value) }.join(', ') %>
+Valid values: `<%= param[:values].map { |value| value_string(value) }.join('`, `') %>`
 
 <% end -%>
 <% if param[:isnamevar] -%>
@@ -109,14 +109,14 @@ namevar
 
 <% end -%>
 <% if param[:aliases] -%>
-Aliases: <%= param[:aliases].to_s.delete('{').delete('}') %>
+Aliases: `<%= param[:aliases].to_s.delete('{').delete('}') %>`
 
 <% end -%>
 <% if param[:data_type] -%>
 Data type: `<%= param[:data_type] %>`<%= "\n_\*this data type contains a regex that may not be accurately reflected in generated documentation_" if regex_in_data_type?(param[:data_type]) %>
 
 <% end -%>
-<%= param[:description] %>
+<%= word_wrap(param[:description]) %>
 
 <% if options_for_param(param[:name]) -%>
 Options:
@@ -135,7 +135,7 @@ Options:
 
 <% end -%>
 <% if param[:default] -%>
-Default value: <%= value_string(param[:default]) %>
+Default value: `<%= value_string(param[:default]) %>`
 
 <% end -%>
 <% if param[:required_features] -%>

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

@@ -1,25 +1,25 @@
 <% if group.length > 0 -%>
-**<%= group_name %>**
+### <%= group_name %>
 
 <% if priv -%>
-_Public <%= group_name %>_
+#### Public <%= group_name %>
 
 <% group.each do |item| -%>
 <% unless item[:private] -%>
-* [`<%= item[:name] %>`](#<%= item[:link] %>): <%= item[:desc] %>
+* [`<%= item[:name] %>`](#<%= item[:link] %>)<% unless item[:desc].nil? || item[:desc].empty? %>: <%= item[:desc] %><% end %>
 <% end -%>
 <% end -%>
 
-_Private <%= group_name %>_
+#### Private <%= group_name %>
 
 <% group.each do |item| -%>
 <% if item[:private] -%>
-* `<%= item[:name] %>`: <%= item[:desc] %>
+* `<%= item[:name] %>`<% unless item[:desc].nil? || item[:desc].empty? %>: <%= item[:desc] %><% end %>
 <% end -%>
 <% end -%>
 <% else -%>
 <% group.each do |item| -%>
-* [`<%= item[:name] %>`](#<%= item[:link] %>): <%= item[:desc] %>
+* [`<%= item[:name] %>`](#<%= item[:link] %>)<% unless item[:desc].nil? || item[:desc].empty? %>: <%= item[:desc] %><% end %>
 <% end -%>
 <% end -%>
 

data/lib/puppet-strings/version.rb

@@ -1,3 +1,3 @@
 module PuppetStrings
-  VERSION = '2.4.0'.freeze
+  VERSION = '2.5.0'.freeze
 end