(MAINT) Refactor markdown specs and fix markdownlint errors

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/markdownlint_style.rb

@@ -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/spec_helper.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

spec/unit/puppet-strings/markdown_spec.rb

@@ -39,70 +39,79 @@ def parse_data_type_content
     YARD::Parser::SourceParser.parse_string(fixture_content("puppet/type_alias.pp"), :puppet)
   end
 
-  let(:baseline_path) { File.join(File.dirname(__FILE__), "../../fixtures/unit/markdown/#{filename}") }
-  let(:baseline) { File.read(baseline_path) }
+  let(:output) { PuppetStrings::Markdown.generate }
 
   RSpec.shared_examples 'markdown lint checker' do |parameter|
     it 'should not generate markdown lint errors from the rendered markdown', if: mdl_available do
-      pending('Failures are expected')
-      Tempfile.open('md') do |file|
-        PuppetStrings::Markdown.render(file.path)
-
-        expect(File.read(file.path)).to have_no_markdown_lint_errors
-      end
+      expect(output).to have_no_markdown_lint_errors
     end
   end
 
-  describe 'rendering markdown to a file' do
+  describe 'markdown rendering' do
     before(:each) do
       parse_shared_content
     end
 
-    context 'with common Puppet and ruby content' do
-      let(:filename) { 'output.md' }
+    include_examples 'markdown lint checker'
 
-      it 'should output the expected markdown content' do
-        Tempfile.open('md') do |file|
-          PuppetStrings::Markdown.render(file.path)
-          expect(File.read(file.path)).to eq(baseline)
-        end
+    describe 'table of contents' do
+      it 'includes links to public classes' do
+        expect(output).to match(/\[`klass`\]\(#.*\).*simple class/i)
       end
 
-      include_examples 'markdown lint checker'
+      it 'includes links to private classes' do
+        expect(output).to match(/`noparams`.*overview.*noparams/i)
+      end
+
+      it 'includes links to defined types' do
+        expect(output).to match(/\[`klass::dt`\]\(#.*\).*simple defined type/i)
+      end
+
+      it 'includes links to resource types' do
+        expect(output).to match(/\[`apt_key`\]\(#.*\).*resource type.*new api/i)
+        expect(output).to match(/\[`database`\]\(#.*\).*example database.*type/i)
+      end
+
+      it 'includes links to functions' do
+        expect(output).to match(/\[`func`\]\(#.*\).*simple puppet function/i)
+        expect(output).to match(/\[`func3x`\]\(#.*\).*example 3\.x function/i)
+        expect(output).to match(/\[`func4x`\]\(#.*\).*example 4\.x function/i)
+        expect(output).to match(/\[`func4x_1`\]\(#.*\).*example 4\.x function.*one signature/i)
+      end
+
+      it 'includes links to tasks' do
+        expect(output).to match(/\[`backup`\]\(#.*\).*backup your database/i)
+      end
     end
 
     describe 'with Puppet Plans', :if => TEST_PUPPET_PLANS do
-      let(:filename) { 'output_with_plan.md' }
-
       before(:each) do
         parse_plan_content
       end
 
-      it 'should output the expected markdown content' do
-        Tempfile.open('md') do |file|
-          PuppetStrings::Markdown.render(file.path)
-          expect(File.read(file.path)).to eq(baseline)
+      include_examples 'markdown lint checker'
+
+      describe "table of contents" do
+        it 'includes links to plans' do
+          expect(output).to match(/\[`plann`\]\(#.*\).*simple plan/i)
         end
       end
-
-      include_examples 'markdown lint checker'
     end
 
     describe 'with Puppet Data Types', :if => TEST_PUPPET_DATATYPES do
-      let(:filename) { 'output_with_data_types.md' }
-
       before(:each) do
         parse_data_type_content
       end
 
-      it 'should output the expected markdown content' do
-        Tempfile.open('md') do |file|
-          PuppetStrings::Markdown.render(file.path)
-          expect(File.read(file.path)).to eq(baseline)
+      include_examples 'markdown lint checker'
+
+      describe "table of contents" do
+        it 'includes links to data types' do
+          expect(output).to match(/\[`Amodule::ComplexAlias`\]\(#.*\).*Amodule::ComplexAlias/i)
+          expect(output).to match(/\[`Amodule::SimpleAlias`\]\(#.*\).*Amodule::SimpleAlias/i)
+          expect(output).to match(/\[`UnitDataType`\]\(#.*\).*data type in ruby/i)
         end
       end
-
-      include_examples 'markdown lint checker'
     end
   end
 end

spec/unit/puppet-strings/yard/handlers/ruby/data_type_handler_spec.rb

@@ -241,6 +241,8 @@ def suppress_yard_logging
     }
 
     it 'should register a partial data type object' do
+      suppress_yard_logging
+
       expect(subject.size).to eq(1)
       object = subject.first
       expect(object).to be_a(PuppetStrings::Yard::CodeObjects::DataType)