puppet-strings 2.8.0 → 3.0.0

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

@@ -3,9 +3,13 @@
 require 'puppet-strings/markdown/base'
 
 module PuppetStrings::Markdown
+  # Generates Markdown for a Puppet Function.
   class Function < Base
     attr_reader :signatures
 
+    group_name 'Functions'
+    yard_types [:puppet_function]
+
     def initialize(registry)
       @template = 'function.erb'
       super(registry, 'function')
@@ -21,14 +25,14 @@ module PuppetStrings::Markdown
 
     def type
       t = @registry[:type]
-      if /ruby4x/.match?(t)
-        "Ruby 4.x API"
-      elsif /ruby3/.match?(t)
-        "Ruby 3.x API"
-      elsif /ruby/.match?(t)
-        "Ruby"
+      if %r{ruby4x}.match?(t)
+        'Ruby 4.x API'
+      elsif %r{ruby3}.match?(t)
+        'Ruby 3.x API'
+      elsif %r{ruby}.match?(t)
+        'Ruby'
       else
-        "Puppet Language"
+        'Puppet Language'
       end
     end
 
@@ -37,10 +41,11 @@ module PuppetStrings::Markdown
     end
 
     def error_text(text)
-      "#{text.split(' ').drop(1).join(' ')}"
+      text.split(' ').drop(1).join(' ').to_s
     end
   end
 
+  # Implements methods to retrieve information about a function signature.
   class Function::Signature < Base
     def initialize(registry)
       @registry = registry

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Helpers for rendering Markdown
+module PuppetStrings::Markdown::Helpers
+  # Formats code as either inline or a block.
+  #
+  # Note that this does not do any escaping even if the code contains ` or ```.
+  #
+  # @param [String] code The code to format.
+  # @param [Symbol] type The type of the code, e.g. :text, :puppet, or :ruby.
+  # @param [String] block_prefix String to insert before if it’s a block.
+  # @param [String] inline_prefix String to insert before if it’s inline.
+  # @returns [String] Markdown
+  def code_maybe_block(code, type: :puppet, block_prefix: "\n\n", inline_prefix: ' ')
+    if code.include?("\n")
+      "#{block_prefix}```#{type}\n#{code}\n```"
+    else
+      "#{inline_prefix}`#{code}`"
+    end
+  end
+end

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

@@ -3,7 +3,11 @@
 require 'puppet-strings/markdown/base'
 
 module PuppetStrings::Markdown
+  # Generates Markdown for a Puppet Class.
   class PuppetClass < Base
+    group_name 'Classes'
+    yard_types [:puppet_class]
+
     def initialize(registry)
       @template = 'classes_and_defines.erb'
       super(registry, 'class')

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

@@ -3,7 +3,11 @@
 require 'puppet-strings/markdown/base'
 
 module PuppetStrings::Markdown
+  # Generates Markdown for a Puppet Plan.
   class PuppetPlan < Base
+    group_name 'Plans'
+    yard_types [:puppet_plan]
+
     def initialize(registry)
       @template = 'classes_and_defines.erb'
       super(registry, 'plan')

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

@@ -3,7 +3,11 @@
 require 'puppet-strings/markdown/base'
 
 module PuppetStrings::Markdown
+  # Generates Markdown for a Puppet Task.
   class PuppetTask < Base
+    group_name 'Tasks'
+    yard_types [:puppet_task]
+
     def initialize(registry)
       @template = 'puppet_task.erb'
       @registry = registry
@@ -21,6 +25,5 @@ module PuppetStrings::Markdown
     def input_method
       @registry[:input_method]
     end
-
   end
 end

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

@@ -3,7 +3,11 @@
 require 'puppet-strings/markdown/base'
 
 module PuppetStrings::Markdown
+  # Generates Markdown for a Puppet Resource Type.
   class ResourceType < Base
+    group_name 'Resource types'
+    yard_types [:puppet_type]
+
     def initialize(registry)
       @template = 'resource_type.erb'
       super(registry, 'type')
@@ -29,17 +33,23 @@ module PuppetStrings::Markdown
     def properties_and_checks
       return nil if properties.nil? && checks.nil?
 
-      ((properties || []) + (checks || [])).sort_by { |p| p[:name] }
+      ((properties || []) + (checks || [])).sort_by { |p| p[:name] }.map do |prop|
+        prop[:link] = clean_link("$#{name}::#{prop[:name]}")
+        prop
+      end
     end
 
     def parameters
       return nil unless @registry[:parameters]
 
-      @registry[:parameters].sort_by { |p| p[:name] }
+      @registry[:parameters].sort_by { |p| p[:name] }.map do |param|
+        param[:link] = clean_link("$#{name}::#{param[:name]}")
+        param
+      end
     end
 
     def regex_in_data_type?(data_type)
-      m = data_type.match(/\w+\[\/.*\/\]/)
+      m = data_type.match(%r{\w+\[/.*/\]})
       m unless m.nil? || m.length.zero?
     end
   end

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

@@ -50,14 +50,14 @@
 The following parameters are available in the `<%= name %>` <%= @type %>:
 
 <% params.each do |param| -%>
-* [`<%= param[:name] %>`](#<%= param[:name] %>)
+* [`<%= param[:name] %>`](#<%= param[:link] %>)
 <% end -%>
 
 <% params.each do |param| -%>
-##### <a name="<%= param[:name] %>"></a>`<%= param[:name] %>`
+##### <a name="<%= param[:link] %>"></a>`<%= param[:name] %>`
 
 <% if param[:types] -%>
-Data type: `<%= param[:types].join(', ') -%>`
+Data type:<%= code_maybe_block(param[:types].join(', ')) %>
 
 <% end -%>
 <%= param[:text] %>
@@ -79,7 +79,7 @@ Options:
 
 <% end -%>
 <% if defaults && defaults[param[:name]] -%>
-Default value: `<%= value_string(defaults[param[:name]]) %>`
+Default value:<%= code_maybe_block(defaults[param[:name]]) %>
 
 <% end -%>
 <% end -%>

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

@@ -45,11 +45,7 @@
 <% end -%>
 <% end -%>
 <% if alias_of -%>
-Alias of
-
-```puppet
-<%= alias_of %>
-```
+Alias of<%= code_maybe_block(alias_of) %>
 
 <% end -%>
 <% if params -%>
@@ -58,14 +54,14 @@ Alias of
 The following parameters are available in the `<%= name %>` <%= @type %>:
 
 <% params.each do |param| -%>
-* [`<%= param[:name] %>`](#<%= param[:name] %>)
+* [`<%= param[:name] %>`](#<%= param[:link] %>)
 <% end -%>
 
 <% params.each do |param| -%>
-##### <a name="<%= param[:name] %>"></a>`<%= param[:name] %>`
+##### <a name="<%= param[:link] %>"></a>`<%= param[:name] %>`
 
 <% if param[:types] -%>
-Data type: `<%= param[:types].join(', ') -%>`
+Data type:<%= code_maybe_block(param[:types].join(', ')) %>
 
 <% end -%>
 <%= param[:text] %>
@@ -87,7 +83,7 @@ Options:
 
 <% end -%>
 <% if defaults && defaults[param[:name]] -%>
-Default value: `<%= value_string(defaults[param[:name]]) %>`
+Default value:<%= code_maybe_block(defaults[param[:name]]) %>
 
 <% end -%>
 <% end -%>

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

@@ -43,7 +43,7 @@ Raises:
 <% params.each do |param| -%>
 ##### `<%= param[:name]  %>`
 
-Data type: `<%= param[:types][0] %>`
+Data type:<%= code_maybe_block(param[:types][0]) %>
 
 <%= param[:text] %>
 

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

@@ -77,7 +77,7 @@ Raises:
 <% sig.params.each do |param| -%>
 ##### `<%= param[:name]  %>`
 
-Data type: `<%= param[:types][0] %>`
+Data type:<%= code_maybe_block(param[:types][0]) %>
 
 <%= param[:text] %>
 

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

@@ -19,7 +19,7 @@
 ##### `<%= param[:name] %>`
 
 <% if param[:types] -%>
-Data type: `<%= param[:types].join(', ') -%>`
+Data type:<%= code_maybe_block(param[:types].join(', ')) %>
 
 <% end -%>
 <%= param[:text] %>

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

@@ -53,7 +53,7 @@ The following properties are available in the `<%= name %>` <%= @type %>.
 ##### `<%= prop[:name] %>`
 
 <% if prop[:values] -%>
-Valid values: `<%= prop[:values].map { |value| value_string(value) }.join('`, `') %>`
+Valid values: `<%= prop[:values].join('`, `') %>`
 
 <% end -%>
 <% if prop[:isnamevar] -%>
@@ -87,7 +87,7 @@ Options:
 
 <% end -%>
 <% if prop[:default] -%>
-Default value: `<%= prop[:default] %>`
+Default value:<%= code_maybe_block(prop[:default], type: :ruby) %>
 
 <% end -%>
 <% end -%>
@@ -98,14 +98,14 @@ Default value: `<%= prop[:default] %>`
 The following parameters are available in the `<%= name %>` <%= @type %>.
 
 <% parameters.each do |param| -%>
-* [`<%= param[:name] %>`](#<%= param[:name] %>)
+* [`<%= param[:name] %>`](#<%= param[:link] %>)
 <% end -%>
 
 <% parameters.each do |param| -%>
-##### <a name="<%= param[:name] %>"></a>`<%= param[:name] %>`
+##### <a name="<%= param[:link] %>"></a>`<%= param[:name] %>`
 
 <% if param[:values] -%>
-Valid values: `<%= param[:values].map { |value| value_string(value) }.join('`, `') %>`
+Valid values: `<%= param[:values].join('`, `') %>`
 
 <% end -%>
 <% if param[:isnamevar] -%>
@@ -141,7 +141,7 @@ Options:
 
 <% end -%>
 <% if param[:default] -%>
-Default value: `<%= value_string(param[:default]) %>`
+Default value: `<%= param[:default] %>`
 
 <% end -%>
 <% if param[:required_features] -%>

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

@@ -1,26 +1,26 @@
-<% if group.length > 0 -%>
+<% unless items.empty? -%>
 ### <%= group_name %>
+<% if has_public -%>
+<% if has_private # only display public heading if we have both -%>
 
-<% if priv -%>
 #### Public <%= group_name %>
+<% end -%>
 
-<% group.each do |item| -%>
+<% items.each do |item| -%>
 <% unless item[:private] -%>
 * [`<%= item[:name] %>`](#<%= item[:link] %>)<% unless item[:desc].nil? || item[:desc].empty? %>: <%= item[:desc] %><% end %>
 <% end -%>
 <% end -%>
+<% end -%>
+<% if has_private -%>
 
 #### Private <%= group_name %>
 
-<% group.each do |item| -%>
+<% items.each do |item| -%>
 <% if item[:private] -%>
 * `<%= item[:name] %>`<% unless item[:desc].nil? || item[:desc].empty? %>: <%= item[:desc] %><% end %>
 <% end -%>
 <% end -%>
-<% else -%>
-<% group.each do |item| -%>
-* [`<%= item[:name] %>`](#<%= item[:link] %>)<% unless item[:desc].nil? || item[:desc].empty? %>: <%= item[:desc] %><% end %>
-<% end -%>
 <% end -%>
 
 <% end -%>

data/lib/puppet-strings/markdown.rb

@@ -4,30 +4,59 @@ require 'puppet-strings/json'
 
 # module for parsing Yard Registries and generating markdown
 module PuppetStrings::Markdown
-  require_relative 'markdown/puppet_classes'
-  require_relative 'markdown/functions'
-  require_relative 'markdown/defined_types'
-  require_relative 'markdown/data_types'
-  require_relative 'markdown/resource_types'
-  require_relative 'markdown/puppet_tasks'
-  require_relative 'markdown/puppet_plans'
-  require_relative 'markdown/table_of_contents'
+  require_relative 'markdown/puppet_class'
+  require_relative 'markdown/function'
+  require_relative 'markdown/defined_type'
+  require_relative 'markdown/data_type'
+  require_relative 'markdown/resource_type'
+  require_relative 'markdown/puppet_task'
+  require_relative 'markdown/puppet_plan'
+
+  # Get classes that handle collecting and rendering each section/group.
+  #
+  # @return [Array[class]] The classes
+  def self.groups
+    [
+      PuppetStrings::Markdown::PuppetClass,
+      PuppetStrings::Markdown::DefinedType,
+      PuppetStrings::Markdown::ResourceType,
+      PuppetStrings::Markdown::Function,
+      PuppetStrings::Markdown::DataType,
+      PuppetStrings::Markdown::PuppetTask,
+      PuppetStrings::Markdown::PuppetPlan,
+    ]
+  end
 
   # generates markdown documentation
   # @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
+    output = [
+      "# Reference\n\n",
+      "<!-- DO NOT EDIT: This document was generated by Puppet Strings -->\n\n",
+      "## Table of Contents\n\n",
+    ]
+
+    # Create table of contents
+    template = erb(File.join(__dir__, 'markdown', 'templates', 'table_of_contents.erb'))
+    groups.each do |group|
+      group_name = group.group_name
+      items = group.items.map { |item| item.toc_info }
+      has_private = items.any? { |item| item[:private] }
+      has_public = items.any? { |item| !item[:private] }
+
+      output << template.result(binding)
+    end
+
+    # Create actual contents
+    groups.each do |group|
+      items = group.items.reject { |item| item.private? }
+      unless items.empty?
+        output << "## #{group.group_name}\n\n"
+        output.append(items.map { |item| item.render })
+      end
+    end
+
+    output.join('')
   end
 
   # mimicks the behavior of the json render, although path will never be nil
@@ -41,4 +70,17 @@ module PuppetStrings::Markdown
       YARD::Logger.instance.debug "Wrote markdown to #{path}"
     end
   end
+
+  # Helper function to load an ERB template.
+  #
+  # @param [String] path The full path to the template file.
+  # @return [ERB] Template
+  def self.erb(path)
+    if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('2.6.0')
+      ERB.new(File.read(path), trim_mode: '-')
+    else
+      # This outputs warnings in Ruby 2.6+.
+      ERB.new(File.read(path), nil, '-')
+    end
+  end
 end

data/lib/puppet-strings/monkey_patches/display_object_command.rb

@@ -4,9 +4,12 @@
 # namespace, but this is disabled in our base object, and so instead gets
 # URL-encoded.
 require 'yard/server/commands/display_object_command'
+
+# Monkey patch YARD::Server::Commands::DisplayObjectCommand object_path.
 class YARD::Server::Commands::DisplayObjectCommand
   private
-  alias_method :object_path_yard, :object_path
+
+  alias object_path_yard object_path
   def object_path
     object_path_yard.gsub('_3A', ':')
   end

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

@@ -5,7 +5,7 @@ require 'puppet-strings'
 # Implements the strings:generate task.
 namespace :strings do
   desc 'Generate Puppet documentation with YARD.'
-  task :generate, [:patterns, :debug, :backtrace, :markup, :json, :markdown, :yard_args] do |t, args|
+  task :generate, [:patterns, :debug, :backtrace, :markup, :json, :markdown, :yard_args] do |_t, args|
     patterns = args[:patterns]
     patterns = patterns.split if patterns
     patterns ||= PuppetStrings::DEFAULT_SEARCH_PATTERNS
@@ -16,7 +16,7 @@ namespace :strings do
       markup: args[:markup] || 'markdown',
     }
 
-    raise("Error: Both JSON and Markdown output have been selected. Please select one.") if args[:json] == 'true' && args[:markdown] == 'true'
+    raise('Error: Both JSON and Markdown output have been selected. Please select one.') if args[:json] == 'true' && args[:markdown] == 'true'
 
     # rubocop:disable Style/PreferredHashMethods
     # Because of Ruby, true and false from the args are both strings and both true. Here,
@@ -28,16 +28,14 @@ namespace :strings do
     # @param [Symbol] possible format option
     # @return nil
     def parse_format_option(args, options, format)
-      if args.has_key? format
-        options[format] = args[format] == 'false' || args[format].empty? ? false : true
-        if options[format]
-          options[:path] = args[format] == 'true' ? nil : args[format]
-        end
-      end
+      return unless args.has_key? format
+      options[format] = args[format] == 'false' || args[format].empty? ? false : true
+      return unless options[format]
+      options[:path] = args[format] == 'true' ? nil : args[format]
     end
     # rubocop:enable Style/PreferredHashMethods
 
-    %i[json markdown].each { |format| parse_format_option(args, options, format) }
+    [:json, :markdown].each { |format| parse_format_option(args, options, format) }
 
     warn('yard_args behavior is a little dodgy, use at your own risk') if args[:yard_args]
     options[:yard_args] = args[:yard_args].split if args.key? :yard_args
@@ -47,7 +45,7 @@ namespace :strings do
 
   namespace :generate do
     desc 'Generate Puppet Reference documentation.'
-    task :reference, [:patterns, :debug, :backtrace] do |t, args|
+    task :reference, [:patterns, :debug, :backtrace] do |_t, args|
       Rake::Task['strings:generate'].invoke(args[:patterns], args[:debug], args[:backtrace], nil, 'false', 'true')
     end
   end

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

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
+require 'English'
 require 'puppet-strings/tasks'
 
 namespace :strings do
   namespace :gh_pages do
     task :checkout do
       if Dir.exist?('doc')
-        fail "The 'doc' directory (#{File.expand_path('doc')}) is not a Git repository! Remove it and run the Rake task again." unless Dir.exist?('doc/.git')
+        raise "The 'doc' directory (#{File.expand_path('doc')}) is not a Git repository! Remove it and run the Rake task again." unless Dir.exist?('doc/.git')
 
         Dir.chdir('doc') do
           system 'git checkout gh-pages'
@@ -14,7 +15,7 @@ namespace :strings do
         end
       else
         git_uri = `git config --get remote.origin.url`.strip
-        fail "Could not determine the remote URL for origin: ensure the current directory is a Git repro with a remote named 'origin'." unless $?.success?
+        raise "Could not determine the remote URL for origin: ensure the current directory is a Git repro with a remote named 'origin'." unless $CHILD_STATUS.success?
 
         Dir.mkdir('doc')
         Dir.chdir('doc') do
@@ -29,7 +30,7 @@ namespace :strings do
     task :configure do
       unless File.exist?(File.join('doc', '_config.yml'))
         Dir.chdir('doc') do
-          File.open('_config.yml', 'w+') {|f| f.write("include: _index.html") }
+          File.open('_config.yml', 'w+') { |f| f.write('include: _index.html') }
         end
       end
     end
@@ -37,7 +38,7 @@ namespace :strings do
     task :push do
       output = `git describe --long 2>/dev/null`
       # If a project has never been tagged, fall back to latest SHA
-      output.empty? ? git_sha = `git log --pretty=format:'%H' -n 1` : git_sha = output
+      git_sha = output.empty? ? `git log --pretty=format:'%H' -n 1` : output
 
       Dir.chdir('doc') do
         system 'git add .'
@@ -47,7 +48,7 @@ namespace :strings do
     end
 
     desc 'Update docs on the gh-pages branch and push to GitHub.'
-    task :update => [
+    task update: [
       :checkout,
       :'strings:generate',
       :configure,

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'puppet-strings'
+require 'tempfile'
+
+namespace :strings do
+  namespace :validate do
+    desc 'Validate the reference is up to date'
+    task :reference, [:patterns, :debug, :backtrace] do |_t, args|
+      filename = 'REFERENCE.md'
+
+      unless File.exist?(filename)
+        STDERR.puts "#{filename} does not exist"
+        exit 1
+      end
+
+      patterns = args[:patterns]
+      patterns = patterns.split if patterns
+      patterns ||= PuppetStrings::DEFAULT_SEARCH_PATTERNS
+
+      generated = Tempfile.create do |file|
+        options = {
+          debug: args[:debug] == 'true',
+          backtrace: args[:backtrace] == 'true',
+          json: false,
+          markdown: true,
+          path: file,
+        }
+        PuppetStrings.generate(patterns, options)
+
+        file.read
+      end
+
+      existing = File.read(filename)
+
+      if generated != existing
+        STDERR.puts "#{filename} is outdated"
+        exit 1
+      end
+    end
+  end
+end

data/lib/puppet-strings/tasks.rb

@@ -3,10 +3,9 @@
 require 'rake'
 require 'rake/tasklib'
 
-module PuppetStrings
-  # The module for Puppet Strings rake tasks.
-  module Tasks
-    require 'puppet-strings/tasks/generate.rb'
-    require 'puppet-strings/tasks/gh_pages.rb'
-  end
+# The module for Puppet Strings rake tasks.
+module PuppetStrings::Tasks
+  require 'puppet-strings/tasks/generate.rb'
+  require 'puppet-strings/tasks/gh_pages.rb'
+  require 'puppet-strings/tasks/validate.rb'
 end

data/lib/puppet-strings/version.rb

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

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

@@ -13,7 +13,7 @@ class PuppetStrings::Yard::CodeObjects::Classes < PuppetStrings::Yard::CodeObjec
   # Gets the display name of the group.
   # @param [Boolean] prefix whether to show a prefix. Ignored for Puppet group namespaces.
   # @return [String] Returns the display name of the group.
-  def name(prefix = false)
+  def name(_prefix = false)
     'Puppet Classes'
   end
 end
@@ -53,7 +53,7 @@ class PuppetStrings::Yard::CodeObjects::Class < PuppetStrings::Yard::CodeObjects
     hash[:line] = line
     hash[:inherits] = statement.parent_class if statement.parent_class
     hash[:docstring] = PuppetStrings::Yard::Util.docstring_to_hash(docstring)
-    defaults = Hash[*parameters.reject{ |p| p[1].nil? }.flatten]
+    defaults = Hash[*parameters.reject { |p| p[1].nil? }.flatten]
     hash[:defaults] = defaults unless defaults.nil? || defaults.empty?
     hash[:source] = source unless source.nil? || source.empty?
     hash