Merge pull request #234 from scotje/maint_spec_cleanups

sheenaajay · web-flow · commit cee0da1fbb12 · 2020-05-27T13:00:52.000+01:00
(MAINT) Fix markdown lint errors and misc testing cleanups
diff --git a/.gitignore b/.gitignore
@@ -39,8 +39,8 @@ Gemfile.lock
 /log/
 /*.gem
 /spec/acceptance/nodesets/
-/spec/fixtures/manifests/
 /spec/fixtures/modules/
+/spec/fixtures/manifests/
 /inventory.yaml
 
 ## local coverage results
diff --git a/.rubocop.yml b/.rubocop.yml
@@ -7,6 +7,7 @@ AllCops:
     - 'lib/puppet-strings/yard/templates/**/*'
     # Ignore fixtures we do not control
     - spec/fixtures/modules/**/*
+    - spec/fixtures/ruby/**/*
 
 # DISABLED - not useful
 Bundler/OrderedGems:
diff --git a/Rakefile b/Rakefile
@@ -43,6 +43,8 @@ RSpec::Core::RakeTask.new(:spec) do |t|
   t.exclude_pattern = "spec/acceptance/**/*.rb"
 end
 
+task :spec => :spec_clean
+
 # Add our own tasks
 require 'puppet-strings/tasks'
 
diff --git a/lib/puppet-strings.rb b/lib/puppet-strings.rb
@@ -27,8 +27,9 @@ def self.generate(search_patterns = DEFAULT_SEARCH_PATTERNS, options = {})
 
     # Format the arguments to YARD
     args = ['doc']
+    args << '--no-progress'
     args << '--debug'     if options[:debug]
-    args << '--backtrace' if options[:backtrace]
+    args << '--backtrace' if options[:debug]
     args << "-m#{options[:markup] || 'markdown'}"
 
     file = nil
@@ -42,7 +43,6 @@ def self.generate(search_patterns = DEFAULT_SEARCH_PATTERNS, options = {})
       args << '-n'
       args << '-q' unless file
       args << '--no-stats' unless file
-      args << '--no-progress' unless file
     end
 
     yard_args = options[:yard_args]
diff --git a/lib/puppet-strings/markdown.rb b/lib/puppet-strings/markdown.rb
@@ -14,7 +14,7 @@ module PuppetStrings::Markdown
   # generates markdown documentation
   # @return [String] markdown doc
   def self.generate
-    final = "# Reference\n"
+    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
diff --git a/lib/puppet-strings/markdown/base.rb b/lib/puppet-strings/markdown/base.rb
@@ -169,6 +169,12 @@ def private?
       @tags.any? { |tag| tag[:tag_name] == 'api' && tag[:text] == 'private' }
     end
 
+    def word_wrap(text, line_width: 120, break_sequence: "\n")
+      text.split("\n").collect! 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}")
diff --git a/lib/puppet-strings/markdown/templates/classes_and_defines.erb b/lib/puppet-strings/markdown/templates/classes_and_defines.erb
@@ -24,10 +24,10 @@
 * **See also**
 <% see.each do |sa| -%>
 <% if sa[:name] -%>
-<%= sa[:name] %>
+<%= "  * #{sa[:name]}" %>
 <% end -%>
 <% if sa[:text] -%>
-<%= sa[:text] %>
+  <%= "  * #{sa[:text]}" %>
 <% end -%>
 <% end -%>
 
diff --git a/lib/puppet-strings/markdown/templates/data_type.erb b/lib/puppet-strings/markdown/templates/data_type.erb
@@ -24,10 +24,10 @@
 * **See also**
 <% see.each do |sa| -%>
 <% if sa[:name] -%>
-<%= sa[:name] %>
+<%= "  * #{sa[:name]}" %>
 <% end -%>
 <% if sa[:text] -%>
-<%= sa[:text] %>
+<%= "  * #{sa[:text]}" %>
 <% end -%>
 <% end -%>
 
diff --git a/lib/puppet-strings/markdown/templates/function.erb b/lib/puppet-strings/markdown/templates/function.erb
@@ -55,6 +55,7 @@ Returns: `<%= sig.return_type %>`<% if sig.return_val %> <%= sig.return_val %><%
 <% end -%>
 <% if raises -%>
 Raises:
+
 <% raises.each do |r| -%>
 * <%= error_type(r[:text]) %> <%= error_text(r[:text]) %>
 <% end -%>
diff --git a/lib/puppet-strings/markdown/templates/resource_type.erb b/lib/puppet-strings/markdown/templates/resource_type.erb
@@ -24,10 +24,10 @@
 * **See also**
 <% see.each do |sa| -%>
 <% if sa[:name] -%>
-<%= sa[:name] %>
+<%= "  * #{sa[:name]}" %>
 <% end -%>
 <% if sa[:text] -%>
-<%= sa[:text] %>
+<%= "  * #{sa[:text]}" %>
 <% end -%>
 <% end -%>
 
@@ -116,7 +116,7 @@ Aliases: <%= param[:aliases].to_s.delete('{').delete('}') %>
 Data type: `<%= param[:data_type] %>`<%= "\n_\*this data type contains a regex that may not be accurately reflected in generated documentation_" if regex_in_data_type?(param[:data_type]) %>
 
 <% end -%>
-<%= param[:description] %>
+<%= word_wrap(param[:description]) %>
 
 <% if options_for_param(param[:name]) -%>
 Options:
diff --git a/lib/puppet-strings/markdown/templates/table_of_contents.erb b/lib/puppet-strings/markdown/templates/table_of_contents.erb
@@ -1,16 +1,16 @@
 <% if group.length > 0 -%>
-**<%= group_name %>**
+### <%= group_name %>
 
 <% if priv -%>
-_Public <%= group_name %>_
+#### Public <%= group_name %>
 
 <% group.each do |item| -%>
 <% unless item[:private] -%>
 * [`<%= item[:name] %>`](#<%= item[:link] %>)<% unless item[:desc].nil? || item[:desc].empty? %>: <%= item[:desc] %><% end %>
 <% end -%>
 <% end -%>
 
-_Private <%= group_name %>_
+#### Private <%= group_name %>
 
 <% group.each do |item| -%>
 <% if item[:private] -%>
diff --git a/spec/fixtures/json/backup.json b/spec/fixtures/json/backup.json
@@ -0,0 +1,22 @@
+{
+  "description": "Allows you to backup your database to local file.",
+  "input_method": "stdin",
+  "parameters": {
+    "database": {
+      "description": "Database to connect to",
+      "type": "Optional[String[1]]"
+    },
+    "user": {
+      "description": "The user",
+      "type": "Optional[String[1]]"
+    },
+    "password": {
+      "description": "The password",
+      "type": "Optional[String[1]]"
+    },
+     "sql": {
+      "description": "Path to file you want backup to",
+      "type": "String[1]"
+    }
+  }
+}
diff --git a/spec/fixtures/puppet/class.pp b/spec/fixtures/puppet/class.pp
@@ -0,0 +1,66 @@
+# An overview for a simple class.
+# @summary A simple class.
+# @todo Do a thing
+# @note some note
+# @since 1.0.0
+# @see www.puppet.com
+# @example This is an example
+#  class { 'klass':
+#    param1 => 1,
+#    param3 => 'foo',
+#  }
+# @example This is another example
+#  class { 'klass':
+#    param1 => 1,
+#    param3 => 'foo',
+#  }
+# @raise SomeError
+# @param param1 First param.
+# @param param2 Second param.
+# @option param2 [String] :opt1 something about opt1
+# @option param2 [Hash] :opt2 a hash of stuff
+# @param param3 Third param.
+# @param param4 Fourth param.
+# @enum param4 :one One option
+# @enum param4 :two Second option
+#
+class klass (
+  Integer $param1 = 1,
+  $param2 = undef,
+  String $param3 = 'hi',
+  Enum['one', 'two'] $param4 = 'two',
+) inherits foo::bar {
+}
+
+# Overview for class noparams
+# @api private
+class noparams () {}
+
+# An overview for a simple defined type.
+# @summary A simple defined type.
+# @since 1.1.0
+# @see www.puppet.com
+# @example Here's an example of this type:
+#  klass::dt { 'foo':
+#    param1 => 33,
+#    param4 => false,
+#  }
+# @return shouldn't return squat
+# @raise SomeError
+# @param param1 First param.
+# @param param2 Second param.
+# @option param2 [String] :opt1 something about opt1
+# @option param2 [Hash] :opt2 a hash of stuff
+# @param param3 Third param.
+# @param param4 Fourth param.
+# @param param5 Fifth param.
+# @enum param5 :a Option A
+# @enum param5 :b Option B
+define klass::dt (
+  Integer $param1 = 44,
+  $param2,
+  String $param3 = 'hi',
+  Boolean $param4 = true,
+  Enum['a', 'b'] $param5 = 'a'
+) {
+}
diff --git a/spec/fixtures/puppet/function.pp b/spec/fixtures/puppet/function.pp
@@ -0,0 +1,14 @@
+# A simple Puppet function.
+# @param param1 First param.
+# @param param2 Second param.
+# @param param3 Third param.
+# @option param3 [Array] :param3opt Something about this option
+# @param param4 Fourth param.
+# @enum param4 :yes Yes option.
+# @enum param4 :no No option.
+# @raise SomeError this is some error
+# @return [Undef] Returns nothing.
+# @example Test
+#   $result = func(1, 2)
+function func(Integer $param1, $param2, String $param3 = hi, Enum['yes', 'no'] $param4 = 'yes') {
+}
diff --git a/spec/fixtures/puppet/plan.pp b/spec/fixtures/puppet/plan.pp
@@ -0,0 +1,6 @@
+# A simple plan.
+# @param param1 First param.
+# @param param2 Second param.
+# @param param3 Third param.
+plan plann(String $param1, $param2, Integer $param3 = 1) {
+}
diff --git a/spec/fixtures/puppet/type_alias.pp b/spec/fixtures/puppet/type_alias.pp
@@ -0,0 +1,8 @@
+# Documentation for Amodule::SimpleAlias
+type Amodule::SimpleAlias = Variant[Numeric,String[1,20]]
+
+# Documentation for Amodule::ComplexAlias
+type Amodule::ComplexAlias = Struct[{
+  value_type => Optional[ValueType],
+  merge      => Optional[MergeType]
+}]
diff --git a/spec/fixtures/ruby/data_type.rb b/spec/fixtures/ruby/data_type.rb
@@ -0,0 +1,12 @@
+# An example Puppet Data Type in Ruby.
+#
+# @param param1 A variant parameter.
+# @param param2 Optional String parameter.
+Puppet::DataTypes.create_type('UnitDataType') do
+  interface <<-PUPPET
+    attributes => {
+      param1 => Variant[Numeric, String[1,2]],
+      param2 => { type => Optional[String[1]], value => "param2" }
+    }
+    PUPPET
+end
diff --git a/spec/fixtures/ruby/func3x.rb b/spec/fixtures/ruby/func3x.rb
@@ -0,0 +1,12 @@
+# An example 3.x function
+Puppet::Parser::Functions.newfunction(:func3x, doc: <<-DOC
+ Documentation for an example 3.x function.
+ @param param1 [String] The first parameter.
+ @param param2 [Integer] The second parameter.
+ @return [Undef]
+ @example Calling the function.
+   func3x('hi', 10)
+ DOC
+ ) do |*args|
+   #...
+end
diff --git a/spec/fixtures/ruby/func4x.rb b/spec/fixtures/ruby/func4x.rb
@@ -0,0 +1,42 @@
+# An example 4.x function.
+#
+# @example Calling the function
+#   $result = func4x(1, 'foo')
+#
+# @example Calling the function with all args
+#   $result = func4x(1, 'foo', ['bar'])
+Puppet::Functions.create_function(:func4x) do
+  # An overview for the first overload.
+  # @raise SomeError this is some error
+  # @param param1 The first parameter.
+  # @param param2 The second parameter.
+  # @option param2 [String] :option an option
+  # @option param2 [String] :option2 another option
+  # @param param3 The third parameter.
+  # @param param4 The fourth parameter.
+  # @enum param4 :one Option one.
+  # @enum param4 :two Option two.
+  # @return Returns nothing.
+  # @example Calling the function foo
+  #   $result = func4x(1, 'foooo')
+  #
+  dispatch :foo do
+    param          'Integer',       :param1
+    param          'Any',           :param2
+    optional_param 'Array[String]', :param3
+    optional_param 'Enum[one, two]', :param4
+    return_type 'Undef'
+  end
+
+  # An overview for the second overload.
+  # @param param The first parameter.
+  # @param block The block parameter.
+  # @return Returns a string.
+  # @example Calling the function bar
+  #   $result = func4x(1, 'bar', ['foo'])
+  dispatch :other do
+    param 'Boolean', :param
+    block_param
+    return_type 'String'
+  end
+end
diff --git a/spec/fixtures/ruby/func4x_1.rb b/spec/fixtures/ruby/func4x_1.rb
@@ -0,0 +1,9 @@
+# An example 4.x function with only one signature.
+Puppet::Functions.create_function(:func4x_1) do
+  # @param param1 The first parameter.
+  # @return [Undef] Returns nothing.
+  dispatch :foobarbaz do
+    param          'Integer',       :param1
+  end
+end
+
diff --git a/spec/fixtures/ruby/provider.rb b/spec/fixtures/ruby/provider.rb
@@ -0,0 +1,11 @@
+Puppet::Type.type(:database).provide :linux do
+  desc 'An example provider on Linux.'
+  confine kernel: 'Linux'
+  confine osfamily: 'RedHat'
+  defaultfor :kernel => 'Linux'
+  defaultfor :osfamily => 'RedHat', :operatingsystemmajrelease => '7'
+  has_feature :implements_some_feature
+  has_feature :some_other_feature
+  commands foo: '/usr/bin/foo'
+end
+
diff --git a/spec/fixtures/ruby/resource_api.rb b/spec/fixtures/ruby/resource_api.rb
@@ -0,0 +1,39 @@
+Puppet::ResourceApi.register_type(
+  name: 'apt_key',
+  docs: <<-EOS,
+@summary Example resource type using the new API.
+@raise SomeError
+This type provides Puppet with the capabilities to manage GPG keys needed
+by apt to perform package validation. Apt has it's own GPG keyring that can
+be manipulated through the `apt-key` command.
+@example here's an example
+  apt_key { '6F6B15509CF8E59E6E469F327F438280EF8D349F':
+    source => 'http://apt.puppetlabs.com/pubkey.gpg'
+  }
+
+**Autorequires**:
+If Puppet is given the location of a key file which looks like an absolute
+path this type will autorequire that file.
+  EOS
+  attributes:   {
+    ensure:      {
+      type: 'Enum[present, absent]',
+      desc: 'Whether this apt key should be present or absent on the target system.'
+    },
+    id:          {
+      type:      'Variant[Pattern[/\A(0x)?[0-9a-fA-F]{8}\Z/], Pattern[/\A(0x)?[0-9a-fA-F]{16}\Z/], Pattern[/\A(0x)?[0-9a-fA-F]{40}\Z/]]',
+      behaviour: :namevar,
+      desc:      'The ID of the key you want to manage.',
+    },
+    # ...
+    created:     {
+      type:      'String',
+      behaviour: :read_only,
+      desc:      'Date the key was created, in ISO format.',
+    },
+  },
+  autorequires: {
+    file:    '$source', # will evaluate to the value of the `source` attribute
+    package: 'apt',
+  },
+)
diff --git a/spec/fixtures/ruby/resource_type.rb b/spec/fixtures/ruby/resource_type.rb
diff --git a/spec/markdownlint_style.rb b/spec/markdownlint_style.rb
diff --git a/spec/spec_helper.rb b/spec/spec_helper.rb
diff --git a/spec/unit/puppet-strings/markdown_spec.rb b/spec/unit/puppet-strings/markdown_spec.rb
diff --git a/spec/unit/puppet-strings/yard/handlers/ruby/data_type_handler_spec.rb b/spec/unit/puppet-strings/yard/handlers/ruby/data_type_handler_spec.rb
