openvox-strings 5.0.0

data/README.md

@@ -0,0 +1,116 @@
+# openvox-strings
+
+[![License](https://img.shields.io/github/license/voxpupuli/openvox-strings.svg)](https://github.com/voxpupuli/openvox-strings/blob/master/LICENSE)
+[![Release](https://github.com/voxpupuli/openvox-strings/actions/workflows/release.yml/badge.svg)](https://github.com/voxpupuli/openvox-strings/actions/workflows/release.yml)
+[![Test](https://github.com/voxpupuli/openvox-strings/actions/workflows/ci.yml/badge.svg)](https://github.com/voxpupuli/openvox-strings/actions/workflows/ci.yml)
+[![RubyGem Version](https://img.shields.io/gem/v/openvox-strings.svg)](https://rubygems.org/gems/openvox-strings)
+[![RubyGem Downloads](https://img.shields.io/gem/dt/openvox-strings.svg)](https://rubygems.org/gems/openvox-strings)
+
+openvox-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.
+
+It's a fork of https://github.com/puppetlabs/puppet-strings.
+Some parts of the documentation still refer to to "Puppet Strings"
+
+## Installing Puppet Strings
+
+### Requirements
+
+* Ruby 2.7 or newer
+* OpenVox 7 or newer
+
+For detailed dependencies, please checkout the gemspec file.
+
+### Install Puppet Strings
+
+Installation instructions vary slightly depending on how you have installed Puppet:
+
+#### Installing Puppet Strings with [`puppet-agent`](https://puppet.com/docs/puppet/6.4/about_agent.html#what-puppet-agent-and-puppetserver-are) package
+
+Install the `openvox-strings` gem into the `puppet-agent` environment:
+
+``` bash
+sudo /opt/puppetlabs/puppet/bin/gem install openvox-strings
+```
+
+#### Installing Puppet Strings with standalone `openvox` gem
+
+Install the `openvox-strings` gem into the same Ruby installation where you have installed the `openvox` gem:
+
+``` bash
+gem install openvox-strings
+```
+
+### Configure Puppet Strings (Optional)
+
+To use YARD options with Puppet Strings, specify a `.yardopts` file in the same directory in which you run `puppet strings`.
+
+Puppet Strings supports the Markdown format and automatically sets the YARD `markup` option to `markdown`.
+
+To see a list of available YARD options, run `yard help doc`.
+
+For details about YARD options configuration, see the [YARD docs](http://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md#config).
+
+## Generating documentation with Puppet Strings
+
+By default, Puppet Strings outputs documentation as HTML, or you can specify JSON or Markdown output instead.
+
+Strings generates reference documentation based on the code and Strings code comments in all Puppet and
+Ruby source files under the `./manifests/`, `./functions/`, `./lib/`, `./types/`, and `./tasks/` directories.
+
+Strings outputs HTML of the reference information and the module README to the module's `./doc/` directory. This output can be rendered in any browser.
+
+JSON and Markdown output include the reference documentation only.
+Strings sends JSON output to either STDOUT or to a file.
+Markdown output is written to a REFERENCE.md file in the module's main directory.
+
+See the [Puppet Strings documentation](https://puppet.com/docs/puppet/latest/puppet_strings.html) for complete instructions for generating documentation with Strings.
+
+For code comment style guidelines and examples, see the [Puppet Strings style guide](https://puppet.com/docs/puppet/latest/puppet_strings_style.html).
+
+### Additional Resources
+
+Here are a few other good resources for getting started with documentation:
+
+* [Module README Template](https://puppet.com/docs/puppet/latest/puppet_strings.html)
+* [YARD Getting Started Guide](http://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md)
+* [YARD Tags Overview](http://www.rubydoc.info/gems/yard/file/docs/Tags.md)
+
+## Developing and Contributing
+
+We love contributions from the community!
+
+If you'd like to contribute to `openvox-strings`, check out [CONTRIBUTING.md](https://github.com/voxpupuli/openvox-strings/blob/main/CONTRIBUTING.md) to get information on the contribution process.
+
+### Running Specs
+
+If you plan on developing features or fixing bugs in Puppet Strings, it is essential that you run specs before opening a pull request.
+
+To run specs, run the `spec` rake task:
+
+``` bash
+bundle install --path .bundle/gems
+bundle exec rake spec
+```
+
+### Running Acceptance Tests
+
+To run specs, run the `acceptance` rake task:
+
+``` bash
+bundle install --path .bundle/gems
+bundle exec rake acceptance
+```
+
+## 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/voxpupuli/openvox-strings/issues).
+Check out [CONTRIBUTING.md](https://github.com/voxpupuli/openvox-strings/blob/main/CONTRIBUTING.md) for tips on writing _the best_ issues.
+
+We use semantic version numbers for our releases and recommend that users upgrade to patch releases and minor releases as they become available.
+
+Bug fixes and ongoing development will occur in minor releases for the current major version.

data/lib/openvox-strings/describe.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'openvox-strings/json'
+
+# The module for command line documentation related functionality.
+module OpenvoxStrings::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_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_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),
+      providers: YARD::Registry.all(:puppet_provider).sort_by!(&:name).map!(&:to_hash)
+    }
+    # 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(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, 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, providers = true)
+    puts format("\n%<name>s\n%<underscore>s", 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])
+
+    return unless combined_list.any?
+
+    puts "\nParameters\n----------"
+    combined_list.sort_by { |p| p[:name] }.each { |p| show_one_parameter(p) }
+    return unless providers
+
+    puts "\nProviders\n---------"
+    resource_type[:providers]&.sort_by { |p| p[:name] }&.each { |p| puts p[:name].to_s.ljust(15) }
+  end
+
+  def self.show_one_parameter(parameter)
+    puts format("\n- **%<name>s**\n", name: parameter[:name])
+    puts parameter[:description]
+    puts format('Valid values are `%<values>s`.', values: parameter[:values].join('`, `')) unless parameter[:values].nil?
+    puts format('Requires features %<required_features>s.', required_features: parameter[:required_features]) unless parameter[:required_features].nil?
+  end
+
+  def self.list_one(object)
+    targetlength = 48
+    shortento = targetlength - 4
+    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 "#{object[:name].to_s.ljust(15)} - #{contentstring}"
+  end
+end

data/lib/openvox-strings/json.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'json'
+
+# The module for JSON related functionality.
+module OpenvoxStrings::Json
+  # Renders the current YARD registry as JSON to the given file (or STDOUT if nil).
+  # @param [String] file The path to the output file to render the registry to. If nil, output will be to STDOUT.
+  # @return [void]
+  def self.render(file = nil)
+    document = {
+      puppet_classes: YARD::Registry.all(:puppet_class).sort_by!(&:name).map!(&:to_hash),
+      data_types: YARD::Registry.all(:puppet_data_type).sort_by!(&:name).map!(&:to_hash),
+      data_type_aliases: YARD::Registry.all(:puppet_data_type_alias).sort_by!(&:name).map!(&:to_hash),
+      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),
+      providers: YARD::Registry.all(:puppet_provider).sort_by!(&:name).map!(&:to_hash),
+      puppet_functions: YARD::Registry.all(:puppet_function).sort_by!(&:name).map!(&:to_hash),
+      puppet_tasks: YARD::Registry.all(:puppet_task).sort_by!(&:name).map!(&:to_hash),
+      puppet_plans: YARD::Registry.all(:puppet_plan).sort_by!(&:name).map!(&:to_hash)
+      # TODO: Need Ruby documentation?
+    }
+
+    if file
+      File.open(file, 'w') do |f|
+        f.write(JSON.pretty_generate(document))
+        f.write("\n")
+      end
+    else
+      puts JSON.pretty_generate(document)
+    end
+  end
+end

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

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require 'openvox-strings'
+require 'openvox-strings/json'
+require 'openvox-strings/yard'
+require 'openvox-strings/markdown/helpers'
+
+# Implements classes that make elements in a YARD::Registry hash easily accessible for template.
+module OpenvoxStrings::Markdown
+  # This class makes elements in a YARD::Registry hash easily accessible for templates.
+  #
+  # Here's an example hash:
+  # {:name=>:klass,
+  # :file=>"(stdin)",
+  # :line=>16,
+  # :inherits=>"foo::bar",
+  # :docstring=>
+  #  {:text=>"An overview for a simple class.",
+  #   :tags=>
+  #    [{:tag_name=>"summary", :text=>"A simple class."},
+  #     {:tag_name=>"since", :text=>"1.0.0"},
+  #     {:tag_name=>"see", :name=>"www.puppet.com"},
+  #     {:tag_name=>"deprecated", :text=>"No longer supported and will be removed in a future release"},
+  #     {:tag_name=>"example",
+  #      :text=>
+  #       "class { 'klass':\n" +
+  #       "  param1 => 1,\n" +
+  #       "  param3 => 'foo',\n" +
+  #       "}",
+  #      :name=>"This is an example"},
+  #     {:tag_name=>"author", :text=>"eputnam"},
+  #     {:tag_name=>"option", :name=>"opts"},
+  #     {:tag_name=>"raise", :text=>"SomeError"},
+  #     {:tag_name=>"param",
+  #      :text=>"First param.",
+  #      :types=>["Integer"],
+  #      :name=>"param1"},
+  #     {:tag_name=>"param",
+  #      :text=>"Second param.",
+  #      :types=>["Any"],
+  #      :name=>"param2"},
+  #     {:tag_name=>"param",
+  #      :text=>"Third param.",
+  #      :types=>["String"],
+  #      :name=>"param3"}]},
+  # :defaults=>{"param1"=>"1", "param2"=>"undef", "param3"=>"'hi'"},
+  # :source=>
+  #  "class klass (\n" +
+  #  "  Integer $param1 = 1,\n" +
+  #  "  $param2 = undef,\n" +
+  #  "  String $param3 = 'hi'\n" +
+  #  ") inherits foo::bar {\n" +
+  #  "}"}
+  class Base
+    # Helpers for ERB templates
+    include OpenvoxStrings::Markdown::Helpers
+
+    # Set or return the name of the group
+    #
+    # @param [Optional[String]] Name of the group to set
+    # @return [String] Name of the group
+    def self.group_name(name = nil)
+      @group_name = name if name
+      @group_name
+    end
+
+    # Set or return the types registered with YARD
+    #
+    # @param [Optional[Array[Symbol]]] Array of symbols registered with YARD to set
+    # @return [Array[Symbol]] Array of symbols registered with YARD
+    def self.yard_types(types = nil)
+      @yard_types = types if types
+      @yard_types
+    end
+
+    # @return [Array] list of items
+    def self.items
+      yard_types
+        .flat_map { |type| YARD::Registry.all(type) }
+        .sort_by(&:name)
+        .map(&:to_hash)
+        .map { |i| new(i) }
+    end
+
+    def initialize(registry, component_type)
+      @type = component_type
+      @registry = registry
+      @tags = registry[:docstring][:tags] || []
+    end
+
+    # generate 1:1 tag methods
+    # e.g. {:tag_name=>"author", :text=>"eputnam"}
+    { return_val: 'return',
+      since: 'since',
+      summary: 'summary',
+      note: 'note',
+      todo: 'todo',
+      deprecated: 'deprecated', }.each do |method_name, tag_name|
+      # @return [String] unless the tag is nil or the string.empty?
+      define_method method_name do
+        @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
+
+    # @return [String] top-level name
+    def name
+      @registry[:name]&.to_s
+    end
+
+    # @return [String] 'Overview' text (untagged text)
+    def text
+      @registry[:docstring][:text] unless @registry[:docstring][:text].empty?
+    end
+
+    # @return [String] data type of return value
+    def return_type
+      @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.find { |tag| tag[:tag_name] == 'since' }[:text] if @tags.any? { |tag| tag[:tag_name] == 'since' }
+    end
+
+    # @return [Array] @see tag hashes
+    def see
+      select_tags('see')
+    end
+
+    # @return [Array] parameter tag hashes
+    def params
+      tags = @tags.select { |tag| tag[:tag_name] == 'param' }.map do |param|
+        param[:link] = clean_link("$#{name}::#{param[:name]}")
+        param
+      end
+      tags.empty? ? nil : tags
+    end
+
+    # @return [Array] example tag hashes
+    def examples
+      select_tags('example')
+    end
+
+    # @return [Array] raise tag hashes
+    def raises
+      select_tags('raise')
+    end
+
+    # @return [Array] option tag hashes
+    def options
+      select_tags('option')
+    end
+
+    # @return [Array] enum tag hashes
+    def enums
+      select_tags('enum')
+    end
+
+    # @param parameter_name
+    #   parameter name to match to option tags
+    # @return [Array] option tag hashes that have a parent parameter_name
+    def options_for_param(parameter_name)
+      opts_for_p = options.select { |o| o[:parent] == parameter_name } unless options.nil?
+      opts_for_p unless opts_for_p.nil? || opts_for_p.empty?
+    end
+
+    # @param parameter_name
+    #   parameter name to match to enum tags
+    # @return [Array] enum tag hashes that have a parent parameter_name
+    def enums_for_param(parameter_name)
+      enums_for_p = enums.select { |e| e[:parent] == parameter_name } unless enums.nil?
+      enums_for_p unless enums_for_p.nil? || enums_for_p.empty?
+    end
+
+    # @return [Hash] any defaults found for the component
+    def defaults
+      @registry[:defaults] unless @registry[:defaults].nil?
+    end
+
+    # @return [Hash] information needed for the table of contents
+    def toc_info
+      {
+        name: name.to_s,
+        link: link,
+        desc: summary || @registry[:docstring][:text][0..140].tr("\n", ' '),
+        private: private?,
+      }
+    end
+
+    # @return [String] makes the component name suitable for a GitHub markdown link
+    def link
+      clean_link(name)
+    end
+
+    def private?
+      @tags.any? { |tag| tag[:tag_name] == 'api' && tag[:text] == 'private' }
+    end
+
+    def word_wrap(text, line_width: 120, break_sequence: "\n")
+      return unless text
+
+      text.split("\n").map! 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)
+      begin
+        OpenvoxStrings::Markdown.erb(file).result(binding)
+      rescue StandardError => e
+        raise "Processing #{@registry[:file]}:#{@registry[:line]} with #{file} => #{e}"
+      end
+    end
+
+    private
+
+    def select_tags(name)
+      tags = @tags.select { |tag| tag[:tag_name] == name }
+      tags.empty? ? nil : tags
+    end
+
+    # Convert an input into a string appropriate for an anchor name.
+    #
+    # This converts any character not suitable for an id attribute into a '-'. Generally we're running this on Puppet identifiers for types and
+    # variables, so we only need to worry about the special characters ':' and '$'. With namespaces Puppet variables this should always be produce a
+    # unique result from a unique input, since ':' only appears in pairs, '$' only appears at the beginning, and '-' never appears.
+    #
+    # @param [String] the input to convert
+    # @return [String] the anchor-safe string
+    def clean_link(input)
+      input.tr('^a-zA-Z0-9_-', '-')
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'openvox-strings/markdown/base'
+
+module OpenvoxStrings::Markdown
+  # This class encapsualtes ruby data types and puppet type aliases
+  class DataType < Base
+    attr_reader :alias_of, :functions
+
+    group_name 'Data types'
+    yard_types %i[puppet_data_type puppet_data_type_alias]
+
+    def initialize(registry)
+      @template = 'data_type.erb'
+      super(registry, 'data type')
+      @alias_of = registry[:alias_of] unless registry[:alias_of].nil?
+      @functions = @registry[:functions]&.map { |func| DataType::Function.new(func) }
+    end
+
+    def render
+      super(@template)
+    end
+  end
+
+  # Generates Markdown for a Puppet Function.
+  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/openvox-strings/markdown/defined_type.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'openvox-strings/markdown/base'
+
+module OpenvoxStrings::Markdown
+  # Generates Markdown for a Puppet Defined Type.
+  class DefinedType < Base
+    group_name 'Defined types'
+    yard_types [:puppet_defined_type]
+
+    def initialize(registry)
+      @template = 'classes_and_defines.erb'
+      super(registry, 'defined type')
+    end
+
+    def render
+      super(@template)
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'openvox-strings/markdown/base'
+
+module OpenvoxStrings::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')
+      @signatures = []
+      registry[:signatures].each do |sig|
+        @signatures.push(Signature.new(sig))
+      end
+    end
+
+    def render
+      super(@template)
+    end
+
+    def type
+      t = @registry[:type]
+      if t.include?('ruby4x')
+        'Ruby 4.x API'
+      elsif t.include?('ruby3')
+        'Ruby 3.x API'
+      elsif t.include?('ruby')
+        'Ruby'
+      else
+        'Puppet Language'
+      end
+    end
+
+    def error_type(type)
+      "`#{type.split[0]}`"
+    end
+
+    def error_text(text)
+      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
+      super(@registry, 'function signature')
+    end
+
+    def signature
+      @registry[:signature]
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Helpers for rendering Markdown
+module OpenvoxStrings::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.to_s.include?("\n")
+      "#{block_prefix}```#{type}\n#{code}\n```"
+    else
+      "#{inline_prefix}`#{code}`"
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'openvox-strings/markdown/base'
+
+module OpenvoxStrings::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')
+    end
+
+    def render
+      super(@template)
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'openvox-strings/markdown/base'
+
+module OpenvoxStrings::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')
+    end
+
+    def render
+      super(@template)
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'openvox-strings/markdown/base'
+
+module OpenvoxStrings::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
+      super(registry, 'task')
+    end
+
+    def render
+      super(@template)
+    end
+
+    def supports_noop
+      @registry[:supports_noop]
+    end
+
+    def input_method
+      @registry[:input_method]
+    end
+  end
+end