puppet-strings 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA256:
-  metadata.gz: b656b5430c108d15ea909e2381ca758884b51c910505ab36880f76be538b5eff
-  data.tar.gz: 6951a084211bbdc7d0d760865acae0e839ceadadd8df337d33938097083b4bc1
+SHA1:
+  metadata.gz: 9556dd124a1f5f4dfcaf4457232efbea310988d8
+  data.tar.gz: 3ef01d946f16d66c1d3af2c32345a90364ef57c6
 SHA512:
-  metadata.gz: 0c359ad4b8a62e978e16f01cf17a50e86d9c011fc13ce3bde9757f2f57074d92c8df7b78119b88bd8551510adb3cf2cbe5adb5644e99e2415ed830d6744eccfe
-  data.tar.gz: ed4d414529d500e4dfa696271e757c4daecd3df98c89ab83b2c7f956ac16a1392779c3fcf0d601d1c91c70a75a0e8745ce36bfef6679dac9f36a7cc3428aca76
+  metadata.gz: 516ae9d909f068fc6c25cbb0f8839b06a16509201bfb7081f0f9ee985088a740780495ce00d50ac5d1c12560ac6d35fad7d2234dc31fc206ad79aa3ce8d5ddbb
+  data.tar.gz: eb5ec2204cac028fa9a27d7c5536694e3f07669d854e7323dba6d03d7cfeff369b92358ee19d4db9cb43fcc44df0f57540b1b41080eca6f1e21fc759e1c8d011

data/CHANGELOG.md

@@ -3,16 +3,31 @@
 All significant changes to this repo will be summarized in this file.
 
 
-## [v2.1.0](https://github.com/puppetlabs/puppet-strings/tree/v2.1.0) (2018-06-25)
+## [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)
+
+Added
+
+- \(PDOC-272\) Add required features attribute [\#194](https://github.com/puppetlabs/puppet-strings/pull/194) ([kris-bosland](https://github.com/kris-bosland))
+- \(maint\) Implement a strings:generate:reference task [\#192](https://github.com/puppetlabs/puppet-strings/pull/192) ([ekohl](https://github.com/ekohl))
+- \(PDOC-265\) Add examples to function reference docs [\#188](https://github.com/puppetlabs/puppet-strings/pull/188) ([ekohl](https://github.com/ekohl))
+- \(PDOC-252\) Add describe features to puppet-strings face [\#183](https://github.com/puppetlabs/puppet-strings/pull/183) ([kris-bosland](https://github.com/kris-bosland))
+
+Fixed
+
+- \(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)
 
 [Full Changelog](https://github.com/puppetlabs/puppet-strings/compare/2.0.0...v2.1.0)
 
-**Implemented enhancements:**
+Added
 
 - \(PDOC-212, PDOC-213\) add support for @note and @todo [\#182](https://github.com/puppetlabs/puppet-strings/pull/182) ([eputnam](https://github.com/eputnam))
 - \(PDOC-255\) markdown table of contents update [\#181](https://github.com/puppetlabs/puppet-strings/pull/181) ([eputnam](https://github.com/eputnam))
 
-**Merged pull requests:**
+Fixed
 
 - \(PDOC-259\) relax ruby requirement to 2.1.0 from 2.1.9 [\#184](https://github.com/puppetlabs/puppet-strings/pull/184) ([DavidS](https://github.com/DavidS))
 

data/Gemfile

@@ -18,7 +18,8 @@ group :test do
   gem 'puppetlabs_spec_helper'
   gem 'serverspec'
   gem 'simplecov-console'
-  gem "rspec", "~> 3.1"
+  gem 'rspec', '~> 3.1'
+  gem 'json_spec', '~> 1.1', '>= 1.1.5'
 end
 
 group :acceptance do
@@ -34,4 +35,4 @@ group :development do
   gem 'pry-byebug'
 end
 
-gem 'rubocop', '<= 0.47.0'
+gem 'rubocop', '~> 0.49'

data/Rakefile

@@ -2,6 +2,11 @@ require 'bundler/gem_tasks'
 #require 'puppetlabs_spec_helper/rake_tasks'
 require 'puppet-lint/tasks/puppet-lint'
 
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.exclude_pattern = "spec/acceptance/**/*.rb"
+end
+
 # Add our own tasks
 require 'puppet-strings/tasks'
 

data/lib/puppet-strings.rb

@@ -53,7 +53,7 @@ module PuppetStrings
     YARD::CLI::Yardoc.run(*args)
 
     # If outputting JSON, render the output
-    if options[:json]
+    if options[:json] && !options[:describe]
       render_json(file)
     end
 
@@ -61,6 +61,10 @@ module PuppetStrings
     if options[:markdown]
       render_markdown(file)
     end
+
+    if options[:describe]
+      render_describe(options[:describe_types], options[:describe_list], options[:providers])
+    end
   end
 
   def self.puppet_5?
@@ -77,6 +81,11 @@ module PuppetStrings
     PuppetStrings::Markdown.render(path)
   end
 
+  def self.render_describe(describe_types, list = false, providers = false)
+    require 'puppet-strings/describe'
+    PuppetStrings::Describe.render(describe_types, list, providers)
+  end
+
   # Runs the YARD documentation server.
   # @param [Array<String>] args The arguments to YARD.
   def self.run_server(*args)

data/lib/puppet-strings/describe.rb

@@ -0,0 +1,68 @@
+require 'json'
+require 'puppet-strings/json'
+
+# The module for command line documentation related functionality.
+module PuppetStrings::Describe
+  # Renders requested types or a summarized list in the current YARD registry to STDOUT.
+  # @param [Array] describe_types The list of names of the types to be displayed.
+  # @param [bool] list Create the summarized list instead of describing each type.
+  # @param [bool] providers Show details of the providers.
+  # @return [void]
+  def self.render(describe_types = [], list = false, providers = false)
+    document = {
+      defined_types: YARD::Registry.all(:puppet_defined_type).sort_by!(&:name).map!(&:to_hash),
+      resource_types: YARD::Registry.all(:puppet_type).sort_by!(&:name).map!(&:to_hash),        
+    }
+
+    if list
+      puts "These are the types known to puppet:"
+      document[:resource_types].each { |t| list_one_type(t) }
+    else
+      document[:providers] = YARD::Registry.all(:puppet_provider).sort_by!(&:name).map!(&:to_hash)
+
+      type_names = {}
+      describe_types.each { |name| type_names[name] = true }
+
+      document[:resource_types].each do |t|
+        show_one_type(t, providers) if type_names[t[:name].to_s]
+      end
+    end
+  end
+
+  def self.show_one_type(resource_type, providers = false)
+    puts "\n%{name}\n%{underscore}" % { name: resource_type[:name], underscore: "=" * resource_type[:name].length }
+    puts resource_type[:docstring][:text]
+
+    combined_list = (resource_type[:parameters].nil? ? [] : resource_type[:parameters]) +
+                    (resource_type[:properties].nil? ? [] : resource_type[:properties])
+
+    if combined_list.any?
+      puts "\nParameters\n----------"
+      combined_list.sort_by { |p| p[:name] }.each { |p| show_one_parameter(p) }
+      puts "\nProviders\n---------"
+    end
+    #Show providers here - list or provide details      
+  end
+
+  def self.show_one_parameter(parameter)
+    puts "\n- **%{name}**\n" % { name: parameter[:name] }
+    puts parameter[:description]
+    puts "Valid values are `%{values}`." % { values: parameter[:values].join("`, `") } unless parameter[:values].nil?
+    puts "Requires features %{required_features}." % { required_features: parameter[:required_features] } unless parameter[:required_features].nil?
+  end
+
+  def self.list_one_type(type)
+    targetlength = 48
+    shortento = targetlength - 4
+    contentstring = type[:docstring][:text]
+    end_of_line = contentstring.index("\n")  # "." gives closer results to old describeb, but breaks for '.k5login'
+    if !end_of_line.nil?
+      contentstring = contentstring[0..end_of_line]
+    end
+    if contentstring.length > targetlength
+      contentstring = contentstring[0..shortento] + ' ...'
+    end
+    
+    puts "%-15s - %-s" % [type[:name], contentstring]
+  end
+end

data/lib/puppet-strings/json.rb

@@ -26,42 +26,4 @@ module PuppetStrings::Json
       puts JSON.pretty_generate(document)
     end
   end
-
-  # Converts a list of tags into an array of hashes.
-  # @param [Array] tags List of tags to be converted into an array of hashes.
-  # @return [Array] Returns an array of tag hashes.
-  def self.tags_to_hashes(tags)
-    # Skip over the API tags that are public
-    tags.select { |t| (t.tag_name != 'api' || t.text != 'public') }.map do |t|
-      next t.to_hash if t.respond_to?(:to_hash)
-
-      tag = { tag_name: t.tag_name }
-      # grab nested information for @option tags
-      if tag[:tag_name] == 'option'
-        tag[:opt_name] = t.pair.name
-        tag[:opt_text] = t.pair.text
-        tag[:opt_types] = t.pair.types
-        tag[:parent] = t.name
-      end
-      tag[:text] = t.text if t.text
-      tag[:types] = t.types if t.types
-      tag[:name] = t.name if t.name
-      tag
-    end
-  end
-
-  # Converts a YARD::Docstring (or String) to a docstring hash for JSON output.
-  # @param [YARD::Docstring, String] docstring The docstring to convert to a hash.
-  # @param [Array] select_tags List of tags to select. Other tags will be filtered out.
-  # @return [Hash] Returns a hash representation of the given docstring.
-  def self.docstring_to_hash(docstring, select_tags=nil)
-    hash = {}
-    hash[:text] = docstring
-    if docstring.is_a? YARD::Docstring
-      tags = tags_to_hashes(docstring.tags.select { |t| select_tags.nil? || select_tags.include?(t.tag_name.to_sym) })
-
-      hash[:tags] = tags unless tags.empty?
-    end
-    hash
-  end
 end

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

@@ -60,9 +60,9 @@ module PuppetStrings::Markdown
       :summary => 'summary',
       :note => 'note',
       :todo => 'todo' }.each do |method_name, tag_name|
-      # @return [String] unless the tag is nil or the string.length == 0
+      # @return [String] unless the tag is nil or the string.empty?
       define_method method_name do
-        @tags.select { |tag| tag[:tag_name] == "#{tag_name}" }[0][:text] unless @tags.select { |tag| tag[:tag_name] == "#{tag_name}" }[0].nil? || @tags.select { |tag| tag[:tag_name] == "#{tag_name}" }[0][:text].length.zero?
+        @tags.find { |tag| tag[:tag_name] == tag_name && !tag[:text].empty? }[:text] if @tags.any? { |tag| tag[:tag_name] == tag_name && !tag[:text].empty? }
       end
     end
 
@@ -78,37 +78,37 @@ module PuppetStrings::Markdown
 
     # @return [String] data type of return value
     def return_type
-      @tags.select { |tag| tag[:tag_name] == 'return' }[0][:types][0] unless @tags.select { |tag| tag[:tag_name] == 'return' }[0].nil?
+      @tags.find { |tag| tag[:tag_name] == 'return' }[:types][0] if @tags.any? { |tag| tag[:tag_name] == 'return' }
     end
 
     # @return [String] text from @since tag
     def since
-      @tags.select { |tag| tag[:tag_name] == 'since' }[0][:text] unless @tags.select { |tag| tag[:tag_name] == 'since' }[0].nil?
+      @tags.find { |tag| tag[:tag_name] == 'since' }[:text] if @tags.any? { |tag| tag[:tag_name] == 'since' }
     end
 
     # @return [Array] @see tag hashes
     def see
-      @tags.select { |tag| tag[:tag_name] == 'see' } unless @tags.select { |tag| tag[:tag_name] == 'see' }[0].nil?
+      select_tags('see')
     end
 
     # @return [Array] parameter tag hashes
     def params
-      @tags.select { |tag| tag[:tag_name] == 'param' } unless @tags.select { |tag| tag[:tag_name] == 'param' }[0].nil?
+      select_tags('param')
     end
 
     # @return [Array] example tag hashes
     def examples
-      @tags.select { |tag| tag[:tag_name] == 'example' } unless @tags.select { |tag| tag[:tag_name] == 'example' }[0].nil?
+      select_tags('example')
     end
 
     # @return [Array] raise tag hashes
     def raises
-      @tags.select { |tag| tag[:tag_name] == 'raise' } unless @tags.select { |tag| tag[:tag_name] == 'raise' }[0].nil?
+      select_tags('raise')
     end
 
     # @return [Array] option tag hashes
     def options
-      @tags.select { |tag| tag[:tag_name] == 'option' } unless @tags.select { |tag| tag[:tag_name] == 'option' }[0].nil?
+      select_tags('option')
     end
 
     # @param parameter_name
@@ -119,7 +119,7 @@ module PuppetStrings::Markdown
       opts_for_p unless opts_for_p.nil? || opts_for_p.length.zero?
     end
 
-    # @return [Array] any defaults found for the component
+    # @return [Hash] any defaults found for the component
     def defaults
       @registry[:defaults] unless @registry[:defaults].nil?
     end
@@ -153,12 +153,7 @@ module PuppetStrings::Markdown
     end
 
     def private?
-      result = false
-      api = @tags.find { |tag| tag[:tag_name] == 'api' }
-      unless api.nil?
-        result = api[:text] == 'private' ? true : false
-      end
-      result
+      @tags.any? { |tag| tag[:tag_name] == 'api' && tag[:text] == 'private' }
     end
 
     # @return [String] full markdown rendering of a component
@@ -166,5 +161,12 @@ module PuppetStrings::Markdown
       file = File.join(File.dirname(__FILE__),"templates/#{template}")
       ERB.new(File.read(file), nil, '-').result(binding)
     end
+
+    private
+
+    def select_tags(name)
+      tags = @tags.select { |tag| tag[:tag_name] == name }
+      tags.empty? ? nil : tags
+    end
   end
 end

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

@@ -4,10 +4,13 @@ Type: <%= type %>
 
 <% if text -%>
 <%= text %>
+
 <% elsif summary -%>
 <%= summary %>
+
 <% else -%>
 <%= "The #{name} function." %>
+
 <% end -%>
 <% if todo -%>
 * **TODO** <%= todo %>
@@ -17,7 +20,18 @@ Type: <%= type %>
 * **Note** <%= note %>
 
 <% end -%>
+<% if examples -%>
+#### Examples
 
+<% examples.each do |eg| -%>
+##### <%= eg[:name] %>
+
+```puppet
+<%= eg[:text] %>
+```
+
+<% end -%>
+<% end -%>
 <% signatures.each do |sig| -%>
 #### `<%= sig.signature %>`
 
@@ -45,6 +59,18 @@ Raises:
 * <%= error_type(r[:text]) %> <%= error_text(r[:text]) %>
 <% end -%>
 
+<% end -%>
+<% if sig.examples -%>
+##### Examples
+
+<% sig.examples.each do |eg| -%>
+###### <%= eg[:name] %>
+
+```puppet
+<%= eg[:text] %>
+```
+
+<% end -%>
 <% end -%>
 <% if sig.params -%>
 <% sig.params.each do |param| -%>

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

@@ -121,6 +121,10 @@ Options:
 <% if param[:default] -%>
 Default value: <%= value_string(param[:default]) %>
 
+<% end -%>
+<% if param[:required_features] -%>
+Required features: <%= param[:required_features] %>.
+
 <% end -%>
 <% end -%>
 <% end -%>

data/lib/puppet-strings/tasks/generate.rb

@@ -41,5 +41,11 @@ namespace :strings do
 
     PuppetStrings.generate(patterns, options)
   end
-end
 
+  namespace :generate do
+    desc 'Generate Puppet Reference documentation.'
+    task :reference, [:patterns, :debug, :backtrace] do |t, args|
+      Rake::Task['strings:generate'].invoke(args[:patterns], args[:debug], args[:backtrace], nil, 'false', 'true')
+    end
+  end
+end

data/lib/puppet-strings/version.rb

@@ -1,3 +1,3 @@
 module PuppetStrings
-  VERSION = '2.1.0'.freeze
+  VERSION = '2.2.0'.freeze
 end

data/lib/puppet-strings/yard/code_objects/class.rb

@@ -50,7 +50,7 @@ class PuppetStrings::Yard::CodeObjects::Class < PuppetStrings::Yard::CodeObjects
     hash[:file] = file
     hash[:line] = line
     hash[:inherits] = statement.parent_class if statement.parent_class
-    hash[:docstring] = PuppetStrings::Json.docstring_to_hash(docstring)
+    hash[:docstring] = PuppetStrings::Yard::Util.docstring_to_hash(docstring)
     defaults = Hash[*parameters.select{ |p| !p[1].nil? }.flatten]
     hash[:defaults] = defaults unless defaults.empty?
     hash[:source] = source unless source && source.empty?

data/lib/puppet-strings/yard/code_objects/defined_type.rb

@@ -49,7 +49,7 @@ class PuppetStrings::Yard::CodeObjects::DefinedType < PuppetStrings::Yard::CodeO
     hash[:name] = name
     hash[:file] = file
     hash[:line] = line
-    hash[:docstring] = PuppetStrings::Json.docstring_to_hash(docstring)
+    hash[:docstring] = PuppetStrings::Yard::Util.docstring_to_hash(docstring)
     defaults = Hash[*parameters.select{ |p| !p[1].nil? }.flatten]
     hash[:defaults] = defaults unless defaults.empty?
     hash[:source] = source unless source && source.empty?

data/lib/puppet-strings/yard/code_objects/function.rb

@@ -88,13 +88,13 @@ class PuppetStrings::Yard::CodeObjects::Function < PuppetStrings::Yard::CodeObje
     if self.has_tag? :overload
       # loop over overloads and append onto the signatures array
       self.tags(:overload).each do |o|
-        hash[:signatures] << { :signature => o.signature, :docstring => PuppetStrings::Json.docstring_to_hash(o.docstring, [:param, :option, :return]) }
+        hash[:signatures] << { :signature => o.signature, :docstring => PuppetStrings::Yard::Util.docstring_to_hash(o.docstring, [:param, :option, :return, :example]) }
       end
     else
-      hash[:signatures] << { :signature => self.signature, :docstring =>  PuppetStrings::Json.docstring_to_hash(docstring, [:param, :option, :return]) }
+      hash[:signatures] << { :signature => self.signature, :docstring =>  PuppetStrings::Yard::Util.docstring_to_hash(docstring, [:param, :option, :return, :example]) }
     end
 
-    hash[:docstring] = PuppetStrings::Json.docstring_to_hash(docstring)
+    hash[:docstring] = PuppetStrings::Yard::Util.docstring_to_hash(docstring)
     defaults = Hash[*parameters.select{ |p| !p[1].nil? }.flatten]
     hash[:defaults] = defaults unless defaults.empty?
     hash[:source] = source unless source && source.empty?

data/lib/puppet-strings/yard/code_objects/plan.rb

@@ -47,7 +47,7 @@ class PuppetStrings::Yard::CodeObjects::Plan < PuppetStrings::Yard::CodeObjects:
     hash[:name] = name
     hash[:file] = file
     hash[:line] = line
-    hash[:docstring] = PuppetStrings::Json.docstring_to_hash(docstring)
+    hash[:docstring] = PuppetStrings::Yard::Util.docstring_to_hash(docstring)
     defaults = Hash[*parameters.select{ |p| !p[1].nil? }.flatten]
     hash[:defaults] = defaults unless defaults.empty?
     hash[:source] = source unless source && source.empty?

data/lib/puppet-strings/yard/code_objects/provider.rb

@@ -82,7 +82,7 @@ class PuppetStrings::Yard::CodeObjects::Provider < PuppetStrings::Yard::CodeObje
     hash[:type_name] = type_name
     hash[:file] = file
     hash[:line] = line
-    hash[:docstring] = PuppetStrings::Json.docstring_to_hash(docstring)
+    hash[:docstring] = PuppetStrings::Yard::Util.docstring_to_hash(docstring)
     hash[:confines] = confines if confines && !confines.empty?
     hash[:features] = features if features && !features.empty?
     hash[:defaults] = defaults if defaults && !defaults.empty?