openvox-strings 5.0.0

data/lib/openvox-strings/markdown.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'openvox-strings/json'
+
+# module for parsing Yard Registries and generating markdown
+module OpenvoxStrings::Markdown
+  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
+    [
+      OpenvoxStrings::Markdown::PuppetClass,
+      OpenvoxStrings::Markdown::DefinedType,
+      OpenvoxStrings::Markdown::ResourceType,
+      OpenvoxStrings::Markdown::Function,
+      OpenvoxStrings::Markdown::DataType,
+      OpenvoxStrings::Markdown::PuppetTask,
+      OpenvoxStrings::Markdown::PuppetPlan
+    ]
+  end
+
+  # generates markdown documentation
+  # @return [String] markdown doc
+  def self.generate
+    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(&: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(&:private?)
+      unless items.empty?
+        output << "## #{group.group_name}\n\n"
+        output.append(items.map(&:render))
+      end
+    end
+
+    output.join
+  end
+
+  # mimicks the behavior of the json render, although path will never be nil
+  # @param [String] path path to destination file
+  def self.render(path = nil)
+    if path.nil?
+      puts generate
+      exit
+    else
+      File.write(path, generate)
+      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)
+    ERB.new(File.read(path), trim_mode: '-')
+  end
+end

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

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Monkey patch URL decoding in object displays. Usually :: is interpreted as a
+# 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 object_path_yard object_path
+  def object_path
+    object_path_yard.gsub('_3A', ':')
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'openvox-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|
+    patterns = args[:patterns]
+    patterns = patterns.split if patterns
+    patterns ||= OpenvoxStrings::DEFAULT_SEARCH_PATTERNS
+
+    options = {
+      debug: args[:debug] == 'true',
+      backtrace: args[:backtrace] == 'true',
+      markup: args[:markup] || 'markdown'
+    }
+
+    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,
+    # when the arg is set to false (or empty), set it to real false, else real true. Then,
+    # if the arg is set simply to 'true', assume default behavior is expected and set the path
+    # to nil to elicit that, else set to the path given.
+    # @param [Hash] args from the Rake task cli
+    # @param [Hash] options to send to the generate function
+    # @param [Symbol] possible format option
+    # @return nil
+    def parse_format_option(args, options, format)
+      return unless args.has_key? format
+
+      options[format] = !(args[format] == 'false' || args[format].empty?)
+      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) }
+
+    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
+
+    OpenvoxStrings.generate(patterns, options)
+  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/openvox-strings/tasks/gh_pages.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require 'English'
+require 'openvox-strings/tasks'
+
+namespace :strings do
+  namespace :gh_pages do
+    task :checkout do
+      if Dir.exist?('doc')
+        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'
+          exit 1 unless $?.success?
+          system 'git pull --rebase origin gh-pages'
+          exit 1 unless $?.success?
+        end
+      else
+        git_uri = `git config --get remote.origin.url`.strip
+        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
+          system 'git init'
+          exit 1 unless $?.success?
+          system "git remote add origin #{git_uri}"
+          exit 1 unless $?.success?
+          system 'git pull origin gh-pages'
+          exit 1 unless $?.success?
+          system 'git checkout -b gh-pages'
+          exit 1 unless $?.success?
+        end
+      end
+    end
+
+    task :configure do
+      unless File.exist?(File.join('doc', '_config.yml'))
+        Dir.chdir('doc') do
+          File.write('_config.yml', 'include: _index.html')
+        end
+      end
+    end
+
+    # Task to push the gh-pages branch. Argument :msg_prefix is the beginning
+    # of the message and the actual commit will have "at Revision <git_sha>"
+    # appended.
+    task :push, [:msg_prefix] do |_t, args|
+      msg_prefix = args[:msg_prefix] || '[strings] Generated Documentation Update'
+
+      output = `git describe --long 2>/dev/null`
+      # If a project has never been tagged, fall back to latest SHA
+      git_sha = output.empty? ? `git log --pretty=format:'%H' -n 1` : output
+
+      Dir.chdir('doc') do
+        system 'git add .'
+        exit 1 unless $?.success?
+        system "git commit -m '#{msg_prefix} at Revision #{git_sha}'"
+        # Do not check status of commit, as it will error if there are no changes.
+        system 'git push origin gh-pages -f'
+        exit 1 unless $?.success?
+      end
+    end
+
+    desc 'Update docs on the gh-pages branch and push to GitHub.'
+    task update: %i[
+      checkout
+      strings:generate
+      configure
+      push
+    ]
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'openvox-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)
+        warn "#{filename} does not exist"
+        exit 1
+      end
+
+      patterns = args[:patterns]
+      patterns = patterns.split if patterns
+      patterns ||= OpenvoxStrings::DEFAULT_SEARCH_PATTERNS
+
+      generated = Tempfile.create do |file|
+        options = {
+          debug: args[:debug] == 'true',
+          backtrace: args[:backtrace] == 'true',
+          json: false,
+          markdown: true,
+          path: file
+        }
+        OpenvoxStrings.generate(patterns, options)
+
+        file.read
+      end
+
+      existing = File.read(filename)
+
+      if generated != existing
+        warn "#{filename} is outdated; to regenerate: bundle exec rake strings:generate:reference"
+        exit 1
+      end
+    end
+  end
+end

data/lib/openvox-strings/tasks.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'rake'
+require 'rake/tasklib'
+
+# Ensure OpenvoxStrings is loaded.
+module OpenvoxStrings end
+
+# The module for Puppet Strings rake tasks.
+module OpenvoxStrings::Tasks
+  require 'openvox-strings/tasks/generate'
+  require 'openvox-strings/tasks/gh_pages'
+  require 'openvox-strings/tasks/validate'
+end

data/lib/openvox-strings/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module OpenvoxStrings
+  VERSION = '5.0.0'
+end

data/lib/openvox-strings/yard/code_objects/base.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Implements the base code object.
+class OpenvoxStrings::Yard::CodeObjects::Base < YARD::CodeObjects::NamespaceObject
+  # Allocates a new code object.
+  # @param [Array] args The arguments to initialize the code object with.
+  # @return Returns the code object.
+  def self.new(*args)
+    # Skip the super class' implementation because it detects :: in names and this will cause namespaces in the output we don't want
+    object = Object.class.instance_method(:new).bind_call(self, *args)
+    existing = YARD::Registry.at(object.path)
+    object = existing if existing.instance_of?(self)
+    yield(object) if block_given?
+    object
+  end
+end

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'openvox-strings/yard/code_objects/group'
+
+# Implements the group for Puppet classes.
+class OpenvoxStrings::Yard::CodeObjects::Classes < OpenvoxStrings::Yard::CodeObjects::Group
+  # Gets the singleton instance of the group.
+  # @return Returns the singleton instance of the group.
+  def self.instance
+    super(:puppet_classes)
+  end
+
+  # 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)
+    'Puppet Classes'
+  end
+end
+
+# Implements the Puppet class code object.
+class OpenvoxStrings::Yard::CodeObjects::Class < OpenvoxStrings::Yard::CodeObjects::Base
+  attr_reader :statement, :parameters
+
+  # Initializes a Puppet class code object.
+  # @param [OpenvoxStrings::Parsers::ClassStatement] statement The class statement that was parsed.
+  # @return [void]
+  def initialize(statement)
+    @statement = statement
+    @parameters = statement.parameters.map { |p| [p.name, p.value] }
+    super(OpenvoxStrings::Yard::CodeObjects::Classes.instance, statement.name)
+  end
+
+  # Gets the type of the code object.
+  # @return Returns the type of the code object.
+  def type
+    :puppet_class
+  end
+
+  # Gets the source of the code object.
+  # @return Returns the source of the code object.
+  def source
+    @statement.source
+  end
+
+  # Converts the code object to a hash representation.
+  # @return [Hash] Returns a hash representation of the code object.
+  def to_hash
+    hash = {}
+    hash[:name] = name
+    hash[:file] = file
+    hash[:line] = line
+    hash[:inherits] = statement.parent_class if statement.parent_class
+    hash[:docstring] = OpenvoxStrings::Yard::Util.docstring_to_hash(docstring)
+    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
+  end
+end

data/lib/openvox-strings/yard/code_objects/data_type.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'openvox-strings/yard/code_objects/group'
+require 'openvox-strings/yard/util'
+
+# Implements the group for Puppet DataTypes.
+class OpenvoxStrings::Yard::CodeObjects::DataTypes < OpenvoxStrings::Yard::CodeObjects::Group
+  # Gets the singleton instance of the group.
+  # @return Returns the singleton instance of the group.
+  def self.instance
+    super(:puppet_data_types)
+  end
+
+  # 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)
+    'Puppet Data Types'
+  end
+end
+
+# Implements the Puppet DataType code object.
+class OpenvoxStrings::Yard::CodeObjects::DataType < OpenvoxStrings::Yard::CodeObjects::Base
+  # Initializes a Puppet class code object.
+  # @param [String] The name of the Data Type
+  # @return [void]
+  def initialize(name)
+    super(OpenvoxStrings::Yard::CodeObjects::DataTypes.instance, name)
+    @defaults = {}
+  end
+
+  # Gets the type of the code object.
+  # @return Returns the type of the code object.
+  def type
+    :puppet_data_type
+  end
+
+  # Gets the source of the code object.
+  # @return Returns the source of the code object.
+  def source
+    # Not implemented, but would be nice!
+    nil
+  end
+
+  def add_parameter(name, type, default)
+    tag = docstring.tags(:param).find { |item| item.name == name }
+    if tag.nil?
+      tag = YARD::Tags::Tag.new(:param, '', nil, name)
+      docstring.add_tag(tag)
+    end
+    type = [type] unless type.is_a?(Array)
+    tag.types = type if tag.types.nil?
+    set_parameter_default(name, default)
+  end
+
+  def set_parameter_default(param_name, default)
+    defaults.delete(param_name)
+    defaults[param_name] = default unless default.nil?
+  end
+
+  def parameters
+    docstring.tags(:param).map { |tag| [tag.name, defaults[tag.name]] }
+  end
+
+  def add_function(name, return_type, parameter_types)
+    meth_obj = YARD::CodeObjects::MethodObject.new(self, name, :class)
+
+    # Add return tag
+    meth_obj.add_tag(YARD::Tags::Tag.new(:return, '', return_type))
+
+    # Add parameters
+    parameter_types.each_with_index do |param_type, index|
+      meth_obj.add_tag(YARD::Tags::Tag.new(:param, '', [param_type], "param#{index + 1}"))
+    end
+
+    meths << meth_obj
+  end
+
+  def functions
+    meths
+  end
+
+  # Converts the code object to a hash representation.
+  # @return [Hash] Returns a hash representation of the code object.
+  def to_hash
+    hash = {}
+    hash[:name] = name
+    hash[:file] = file
+    hash[:line] = line
+    hash[:docstring] = OpenvoxStrings::Yard::Util.docstring_to_hash(docstring, %i[param option enum return example])
+    hash[:defaults] = defaults unless defaults.nil? || defaults.empty?
+    hash[:source] = source unless source.nil? || source.empty?
+    hash[:functions] = functions.map do |func|
+      {
+        name: func.name,
+        signature: func.signature,
+        docstring: OpenvoxStrings::Yard::Util.docstring_to_hash(func.docstring, %i[param option enum return example])
+      }
+    end
+    hash
+  end
+end

data/lib/openvox-strings/yard/code_objects/data_type_alias.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'openvox-strings/yard/code_objects/group'
+require 'openvox-strings/yard/util'
+
+# Implements the group for Puppet DataTypeAliases.
+class OpenvoxStrings::Yard::CodeObjects::DataTypeAliases < OpenvoxStrings::Yard::CodeObjects::Group
+  # Gets the singleton instance of the group.
+  # @return Returns the singleton instance of the group.
+  def self.instance
+    super(:puppet_data_type_aliases)
+  end
+
+  # 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)
+    'Puppet Data Type Aliases'
+  end
+end
+
+# Implements the Puppet DataTypeAlias code object.
+class OpenvoxStrings::Yard::CodeObjects::DataTypeAlias < OpenvoxStrings::Yard::CodeObjects::Base
+  attr_reader :statement
+  attr_accessor :alias_of
+
+  # Initializes a Puppet data type alias code object.
+  # @param [OpenvoxStrings::Parsers::DataTypeAliasStatement] statement The data type alias statement that was parsed.
+  # @return [void]
+  def initialize(statement)
+    @statement = statement
+    @alias_of = statement.alias_of
+    super(OpenvoxStrings::Yard::CodeObjects::DataTypeAliases.instance, statement.name)
+  end
+
+  # Gets the type of the code object.
+  # @return Returns the type of the code object.
+  def type
+    :puppet_data_type_alias
+  end
+
+  # Gets the source of the code object.
+  # @return Returns the source of the code object.
+  def source
+    # Not implemented, but would be nice!
+    nil
+  end
+
+  # Converts the code object to a hash representation.
+  # @return [Hash] Returns a hash representation of the code object.
+  def to_hash
+    hash = {}
+    hash[:name] = name
+    hash[:file] = file
+    hash[:line] = line
+    hash[:docstring] = OpenvoxStrings::Yard::Util.docstring_to_hash(docstring)
+    hash[:alias_of] = alias_of
+    hash
+  end
+end

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'openvox-strings/yard/code_objects/group'
+
+# Implements the group for Puppet defined types.
+class OpenvoxStrings::Yard::CodeObjects::DefinedTypes < OpenvoxStrings::Yard::CodeObjects::Group
+  # Gets the singleton instance of the group.
+  # @return Returns the singleton instance of the group.
+  def self.instance
+    super(:puppet_defined_types)
+  end
+
+  # 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)
+    'Defined Types'
+  end
+end
+
+# Implements the Puppet defined type code object.
+class OpenvoxStrings::Yard::CodeObjects::DefinedType < OpenvoxStrings::Yard::CodeObjects::Base
+  attr_reader :statement, :parameters
+
+  # Initializes a Puppet defined type code object.
+  # @param [OpenvoxStrings::Parsers::DefinedTypeStatement] statement The defined type statement that was parsed.
+  # @return [void]
+  def initialize(statement)
+    @statement = statement
+    @parameters = statement.parameters.map { |p| [p.name, p.value] }
+    super(OpenvoxStrings::Yard::CodeObjects::DefinedTypes.instance, statement.name)
+  end
+
+  # Gets the type of the code object.
+  # @return Returns the type of the code object.
+  def type
+    :puppet_defined_type
+  end
+
+  # Gets the source of the code object.
+  # @return Returns the source of the code object.
+  def source
+    @statement.source
+  end
+
+  # Converts the code object to a hash representation.
+  # @return [Hash] Returns a hash representation of the code object.
+  def to_hash
+    hash = {}
+    hash[:name] = name
+    hash[:file] = file
+    hash[:line] = line
+    hash[:docstring] = OpenvoxStrings::Yard::Util.docstring_to_hash(docstring)
+    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
+  end
+end