puppet-strings 4.0.0 → 4.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d62acfc0a3e4fa9561fc3d3291a70335101c9705697b7736c17eb270547a0c2e
-  data.tar.gz: 81606aea417506c5e2d3041d042df2b8a5299b08d6cf517993fe92019bd3b9ec
+  metadata.gz: a436988d26135b32aebfa60a1629c0bb0abe3901498c323ba626720920adb6a5
+  data.tar.gz: 505f15e76bfa4fc30f9f0a3effd3fa6869c28c9c62d824fe84bd0a463a8ae57d
 SHA512:
-  metadata.gz: 261ed46f4fd0da48e210942d6d61b3bbac7dc6e1bb3fabe101a30651b3cb0377e0864ed9f4ff7ebbea477a288ef6e09f477bca366cfd71564b74eda6a60c7d86
-  data.tar.gz: 2aa3781199b8cb71bf9356c92a83df920d433fe07917c80ad500db8c16a54bcbf21ada74fcd41d4a063c6bad6ab9a874e830b4bde82ccfb4170749b31b6f6ba8
+  metadata.gz: 863c8107391d017e15ef16d94b834e7cccf5c6b64e2026f20bd92aa38ba88a21ef635dfe2b80f5ad5008f381fe797368b7d0cf56bb4688a72fd0ddc23230ab49
+  data.tar.gz: 12f98c88971353202a5656798c2c9762b8e4b6806258d89ffbcaade4b84abed6957a045df181da4500e870b170c324f3621269c52f465060464db2b09e067063

data/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](http://semver.org).
 
+## [v4.1.1](https://github.com/puppetlabs/puppet-strings/tree/v4.1.1) - 2023-11-22
+
+[Full Changelog](https://github.com/puppetlabs/puppet-strings/compare/v4.1.0...v4.1.1)
+
+### Fixed
+
+- Fix option tag handling with no data types [#361](https://github.com/puppetlabs/puppet-strings/pull/361) ([seanmil](https://github.com/seanmil))
+
+## [v4.1.0](https://github.com/puppetlabs/puppet-strings/tree/v4.1.0) - 2023-07-04
+
+[Full Changelog](https://github.com/puppetlabs/puppet-strings/compare/v4.0.0...v4.1.0)
+
+### Added
+
+- (CONT-1193) - Add `--providers` and `--list-providers` flags [#357](https://github.com/puppetlabs/puppet-strings/pull/357) ([jordanbreen28](https://github.com/jordanbreen28))
+
 ## [v4.0.0](https://github.com/puppetlabs/puppet-strings/tree/v4.0.0) - 2023-04-25
 
 [Full Changelog](https://github.com/puppetlabs/puppet-strings/compare/v4.0.0.rc.1...v4.0.0)
@@ -13,13 +29,13 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) a
 
 [Full Changelog](https://github.com/puppetlabs/puppet-strings/compare/v3.0.1...v4.0.0.rc.1)
 
+### Changed
+- (CONT-812) Puppet 8 / Ruby 3 support [#348](https://github.com/puppetlabs/puppet-strings/pull/348) ([chelnak](https://github.com/chelnak))
+
 ### Added
 
 - Add deprecated tag [#342](https://github.com/puppetlabs/puppet-strings/pull/342) ([b4ldr](https://github.com/b4ldr))
 
-### Changed
-- (CONT-812) Puppet 8 / Ruby 3 support [#348](https://github.com/puppetlabs/puppet-strings/pull/348) ([chelnak](https://github.com/chelnak))
-
 ## [v3.0.1](https://github.com/puppetlabs/puppet-strings/tree/v3.0.1) - 2022-10-25
 
 [Full Changelog](https://github.com/puppetlabs/puppet-strings/compare/v3.0.0...v3.0.1)
@@ -32,16 +48,16 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) a
 
 [Full Changelog](https://github.com/puppetlabs/puppet-strings/compare/v2.9.0...v3.0.0)
 
-### Added
-
-- (#223) Use code blocks as appropriate in Markdown [#319](https://github.com/puppetlabs/puppet-strings/pull/319) ([danielparks](https://github.com/danielparks))
-- Use tilde heredocs for readability [#317](https://github.com/puppetlabs/puppet-strings/pull/317) ([danielparks](https://github.com/danielparks))
-
 ### Changed
 - (CONT-228) Remove deprecated emit flags [#329](https://github.com/puppetlabs/puppet-strings/pull/329) ([chelnak](https://github.com/chelnak))
 - (CONT-228) Bump ruby version [#326](https://github.com/puppetlabs/puppet-strings/pull/326) ([chelnak](https://github.com/chelnak))
 - (#301) Update minimum Ruby version to 2.5.0 [#313](https://github.com/puppetlabs/puppet-strings/pull/313) ([danielparks](https://github.com/danielparks))
 
+### Added
+
+- (#223) Use code blocks as appropriate in Markdown [#319](https://github.com/puppetlabs/puppet-strings/pull/319) ([danielparks](https://github.com/danielparks))
+- Use tilde heredocs for readability [#317](https://github.com/puppetlabs/puppet-strings/pull/317) ([danielparks](https://github.com/danielparks))
+
 ### Fixed
 
 - (#240) Fix output of default values that are expressions [#315](https://github.com/puppetlabs/puppet-strings/pull/315) ([danielparks](https://github.com/danielparks))
@@ -88,13 +104,13 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) a
 
 [Full Changelog](https://github.com/puppetlabs/puppet-strings/compare/v2.5.0...v2.6.0)
 
+### 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))
+
 ### Added
 
 - Improved markdown templates [#252](https://github.com/puppetlabs/puppet-strings/pull/252) ([kozl](https://github.com/kozl))
 
-### 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))
-
 ### 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))
@@ -181,15 +197,15 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) a
 
 [Full Changelog](https://github.com/puppetlabs/puppet-strings/compare/1.2.1...2.0.0)
 
+### Changed
+- bump required ruby and puppet versions [#178](https://github.com/puppetlabs/puppet-strings/pull/178) ([eputnam](https://github.com/eputnam))
+
 ### Added
 
 - (PDOC-238) add generated message to markdown [#175](https://github.com/puppetlabs/puppet-strings/pull/175) ([eputnam](https://github.com/eputnam))
 - (PDOC-228) puppet plan support [#168](https://github.com/puppetlabs/puppet-strings/pull/168) ([eputnam](https://github.com/eputnam))
 - (PDOC-206) support for tasks [#161](https://github.com/puppetlabs/puppet-strings/pull/161) ([eputnam](https://github.com/eputnam))
 
-### Changed
-- bump required ruby and puppet versions [#178](https://github.com/puppetlabs/puppet-strings/pull/178) ([eputnam](https://github.com/eputnam))
-
 ### Fixed
 
 - (PDOC-36) fix hack for README urls [#176](https://github.com/puppetlabs/puppet-strings/pull/176) ([eputnam](https://github.com/eputnam))

data/README.md

@@ -1,6 +1,8 @@
 # Puppet strings
 
-[![ci](https://github.com/puppetlabs/puppet-strings/actions/workflows/ci.yml/badge.svg)](https://github.com/puppetlabs/puppet-strings/actions/workflows/ci.yml) [![Gem Version](https://badge.fury.io/rb/puppet-strings.svg)](https://badge.fury.io/rb/puppet-strings)
+[![ci](https://github.com/puppetlabs/puppet-strings/actions/workflows/ci.yml/badge.svg)](https://github.com/puppetlabs/puppet-strings/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/puppet-strings.svg)](https://badge.fury.io/rb/puppet-strings)
+[![Code Owners](https://img.shields.io/badge/owners-DevX--team-blue)](https://github.com/puppetlabs/puppet-strings/blob/main/CODEOWNERS)
 
 Puppet Strings generates documentation for Puppet code and extensions written in Puppet and Ruby.
 Strings processes code and YARD-style code comments to create documentation in HTML, Markdown, or JSON formats.
@@ -107,7 +109,7 @@ An example of running the acceptance tests locally with Docker:
 4. Install test items; Puppet Agent, our test module, and the puppet-strings gem built from this source code
 
     ``` bash
-    bundle exec rake 'litmus:install_agent[puppet6]'
+    bundle exec rake 'litmus:install_agent[puppet8]'
     bundle exec rake 'litmus:install_modules_from_directory[./spec/fixtures/acceptance/modules]'
     bundle exec rake litmus:install_gems
     ```
@@ -124,6 +126,10 @@ An example of running the acceptance tests locally with Docker:
     bundle exec rake litmus:tear_down
     ```
 
+## License
+
+This codebase is licensed under Apache 2.0. However, the open source dependencies included in this codebase might be subject to other software licenses such as AGPL, GPL2.0, and MIT.
+
 ## Support
 
 Please log issues in [GitHub issues](https://github.com/puppetlabs/puppet-strings/issues).

data/lib/puppet/face/strings.rb

@@ -3,7 +3,7 @@
 require 'puppet/face'
 
 # Implements the 'puppet strings' interface.
-Puppet::Face.define(:strings, '0.0.1') do
+Puppet::Face.define(:strings, '0.0.1') do # rubocop:disable Metrics/BlockLength
   summary 'Generate Puppet documentation with YARD.'
 
   action(:generate) do
@@ -83,7 +83,10 @@ Puppet::Face.define(:strings, '0.0.1') do
       summary 'list types'
     end
     option '--providers' do
-      summary 'provide details on providers'
+      summary 'provide details on providers for each type'
+    end
+    option '--list-providers' do
+      summary 'list all providers'
     end
 
     # TODO: Implement the rest of describe behavior
@@ -96,6 +99,9 @@ Puppet::Face.define(:strings, '0.0.1') do
     # * --list:
     #   List all types
 
+    # * --list-providers:
+    #   list all providers
+
     # * --meta:
     #   List all metaparameters
 
@@ -160,6 +166,8 @@ Puppet::Face.define(:strings, '0.0.1') do
         generate_options[:describe] = true
         generate_options[:describe_types] = options[:describe_types]
         generate_options[:describe_list] = options[:list]
+        generate_options[:providers] = options[:providers]
+        generate_options[:list_providers] = options[:list_providers]
       end
 
       format = options[:format]

data/lib/puppet-strings/describe.rb

@@ -7,31 +7,38 @@ require 'puppet-strings/json'
 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.
+  # @param [bool] list_types Create the summarized list instead of describing each type.
+  # @param [bool] show_type_providers Show details of the providers of a specified type.
+  # @param [bool] list_providers Create a summarized list of providers.
   # @return [void]
-  def self.render(describe_types = [], list = false, _providers = false)
+  def self.render(describe_types = [], list_types = false, show_type_providers = true, list_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)
+      resource_types: YARD::Registry.all(:puppet_type).sort_by!(&:name).map!(&:to_hash),
+      providers: YARD::Registry.all(:puppet_provider).sort_by!(&:name).map!(&:to_hash)
     }
-
-    if list
+    # if --list flag passed, produce a summarized list of types
+    if list_types
       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)
+      document[:resource_types].each { |t| list_one(t) }
 
+    # if a type(s) has been passed, show the details of that type(s)
+    elsif describe_types
       type_names = {}
       describe_types.each { |name| type_names[name] = true }
 
       document[:resource_types].each do |t|
-        show_one_type(t) if type_names[t[:name].to_s]
+        show_one_type(t, show_type_providers) if type_names[t[:name].to_s]
       end
+
+    # if --providers flag passed, produce a summarized list of providers
+    elsif list_providers
+      puts 'These are the providers known to puppet:'
+      document[:providers].each { |t| list_one(t) }
     end
   end
 
-  def self.show_one_type(resource_type)
+  def self.show_one_type(resource_type, providers = true)
     puts format("\n%<name>s\n%<underscore>s", name: resource_type[:name], underscore: '=' * resource_type[:name].length)
     puts resource_type[:docstring][:text]
 
@@ -42,8 +49,10 @@ module PuppetStrings::Describe
 
     puts "\nParameters\n----------"
     combined_list.sort_by { |p| p[:name] }.each { |p| show_one_parameter(p) }
+    return unless providers
+
     puts "\nProviders\n---------"
-    # Show providers here - list or provide details
+    resource_type[:providers]&.sort_by { |p| p[:name] }&.each { |p| puts p[:name].to_s.ljust(15) }
   end
 
   def self.show_one_parameter(parameter)
@@ -53,14 +62,14 @@ module PuppetStrings::Describe
     puts format('Requires features %<required_features>s.', required_features: parameter[:required_features]) unless parameter[:required_features].nil?
   end
 
-  def self.list_one_type(type)
+  def self.list_one(object)
     targetlength = 48
     shortento = targetlength - 4
-    contentstring = type[:docstring][:text]
+    contentstring = object[:docstring][:text]
     end_of_line = contentstring.index("\n")  # "." gives closer results to old describeb, but breaks for '.k5login'
     contentstring = contentstring[0..end_of_line] unless end_of_line.nil?
     contentstring = "#{contentstring[0..shortento]} ..." if contentstring.length > targetlength
 
-    puts "#{type[:name].to_s.ljust(15)} - #{contentstring}"
+    puts "#{object[:name].to_s.ljust(15)} - #{contentstring}"
   end
 end

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

@@ -70,7 +70,11 @@ Data type:<%= code_maybe_block(param[:types].join(', ')) %>
 Options:
 
 <% options_for_param(param[:name]).each do |o| -%>
+<% if o[:opt_types] -%>
 * **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
+<% else -%>
+* **<%= o[:opt_name] %>**: <%= o[:opt_text] %>
+<% end -%>
 <% end -%>
 
 <% end -%>

data/lib/puppet-strings/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PuppetStrings
-  VERSION = '4.0.0'
+  VERSION = '4.1.1'
 end

data/lib/puppet-strings/yard/handlers/ruby/data_type_handler.rb

@@ -143,6 +143,8 @@ class PuppetStrings::Yard::Handlers::Ruby::DataTypeHandler < PuppetStrings::Yard
       @literal_visitor.visit_this_0(self, ast)
     end
 
+    # TODO: Fix the rubocop violations in this file between the following rubocop:disable/enable lines
+    # rubocop:disable Naming/MethodName
     # ----- The following methods are different/additions from the original Literal_evaluator
     def literal_Object(o)
       # Ignore any other object types
@@ -214,6 +216,7 @@ class PuppetStrings::Yard::Handlers::Ruby::DataTypeHandler < PuppetStrings::Yard
         result[literal(entry.key)] = literal(entry.value)
       end
     end
+    # rubocop:enable Naming/MethodName
   end
 
   # Extracts the datatype attributes from a Puppet Data Type interface hash.

data/lib/puppet-strings/yard/handlers/ruby/function_handler.rb

@@ -322,7 +322,7 @@ class PuppetStrings::Yard::Handlers::Ruby::FunctionHandler < PuppetStrings::Yard
     end
 
     type ||= tag&.types ? tag.type : 'Any'
-    type = optional ? "Optional[#{type}]" : type
+    type = "Optional[#{type}]" if optional
 
     object.parameters << [name, to_puppet_literal(default)]
 

data/lib/puppet-strings/yard/parsers/puppet/parser.rb

@@ -40,6 +40,8 @@ class PuppetStrings::Yard::Parsers::Puppet::Parser < YARD::Parser::Base
 
   private
 
+  # TODO: Fix the rubocop violations in this file between the following rubocop:disable/enable lines
+  # rubocop:disable Naming/MethodName
   def transform_Program(o)
     # Cache the lines of the source text; we'll use this to locate comments
     @lines = o.source_text.lines.to_a
@@ -83,4 +85,5 @@ class PuppetStrings::Yard::Parsers::Puppet::Parser < YARD::Parser::Base
   def transform_Object(o)
     # Ignore anything else (will be compacted out of the resulting array)
   end
+  # rubocop:enable Naming/MethodName
 end

data/lib/puppet-strings/yard/tags/overload_tag.rb

@@ -75,8 +75,8 @@ class PuppetStrings::Yard::Tags::OverloadTag < YARD::Tags::Tag
   # @param [Array] args The args passed to the method.
   # @param block The block passed to the method.
   # @return Returns what the method call on the object would return.
-  def method_missing(method_name, *args, &block)
-    return object.send(method_name, *args, &block) if object.respond_to? method_name
+  def method_missing(method_name, ...)
+    return object.send(method_name, ...) if object.respond_to? method_name
 
     super
   end

data/lib/puppet-strings.rb

@@ -55,7 +55,7 @@ module PuppetStrings
 
     return unless options[:describe]
 
-    render_describe(options[:describe_types], options[:describe_list], options[:providers])
+    render_describe(options[:describe_types], options[:describe_list], options[:providers], options[:list_providers])
   end
 
   def self.puppet_5?
@@ -72,9 +72,9 @@ module PuppetStrings
     PuppetStrings::Markdown.render(path)
   end
 
-  def self.render_describe(describe_types, list = false, providers = false)
+  def self.render_describe(describe_types, list = false, show_providers = true, list_providers = false)
     require 'puppet-strings/describe'
-    PuppetStrings::Describe.render(describe_types, list, providers)
+    PuppetStrings::Describe.render(describe_types, list, show_providers, list_providers)
   end
 
   # Runs the YARD documentation server.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: puppet-strings
 version: !ruby/object:Gem::Version
-  version: 4.0.0
+  version: 4.1.1
 platform: ruby
 authors:
 - Puppet Inc.
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-04-25 00:00:00.000000000 Z
+date: 2023-11-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rgen