(MAINT) Refactor markdown specs and fix markdownlint errors

Author: scotje

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

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}")

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 -%>
 

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 -%>
 

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 -%>

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:

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] -%>

spec/fixtures/json/task.json renamed to spec/fixtures/json/backup.json

@@ -0,0 +1,10 @@
+all
+
+# Update line length to 120 chars.
+rule 'MD013', line_length: 120
+
+# Allow duplicate headings.
+exclude_rule 'MD024'
+
+# Allow trailing punctuation in headings.
+exclude_rule 'MD026'

spec/markdownlint_style.rb

@@ -56,11 +56,11 @@ def lint_markdown(content)
   return [] unless mdl_available
   require 'mdl'
 
-  ruleset = MarkdownLint::RuleSet.new
-  ruleset.load_default
+  # Load default mdl ruleset
+  ruleset = MarkdownLint::RuleSet.new.tap { |r| r.load_default }
 
-  # All rules
-  style = MarkdownLint::Style.load('all', ruleset.rules)
+  # Apply custom style to ruleset rules
+  MarkdownLint::Style.load(File.join(__dir__, 'markdownlint_style.rb'), ruleset.rules)
 
   # Create a document
   doc = MarkdownLint::Doc.new(content, false)
@@ -73,7 +73,7 @@ def lint_markdown(content)
     # record the error
     error_lines.each do |line|
       line += doc.offset # Correct line numbers for any yaml front matter
-      violations << "#{filename}:#{line}: #{id} #{rule.description}"
+      violations << "#{line}: #{id} #{rule.description}: #{doc.lines[line - 1]}"
     end
   end
   violations