rspec-illustrate 0.1.3 → 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d870dec93914bb6ba39750aec5ee4d761ddaf57a
+  data.tar.gz: 00f1fd8e6e03a31c48d0d93ecf0d86e0fa94ab6f
+SHA512:
+  metadata.gz: d3af7d4a069a34fdf20488e10ef6d8996e71aeeb0c2fecb8d3e718580d05dc55d41e1b71999ede0e109580f543a6b7fe03fc1a250eb16def5d69ca9dc3fb7ae4
+  data.tar.gz: 4e226af173505d8fdb5fde8eddb74bb6da99fc842382205495221f77f20b9519d661b57fb3cb65551991f9ae127988f43cf182e147e9c60fff0d27c9e4285dec

data/README.md

@@ -68,14 +68,55 @@ Array
     [1, 2, 3]
 ```
 
+## Import test results and illustrations into YARD
+
+RSpec-Illustrate comes with a template for YARD and an RSpec formatter that
+outputs a specific HTML format that the template can import.
+
+To create the test report you have to execute RSpec with the specific formatter.
+You need to add the following to your `Rakefile`:
+```ruby
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.rspec_opts = "--format RSpec::Formatters::YARD --out ./doc/api.rspec"
+end
+```
+
+Keep in mind that the file must end with `.rspec` in order for the template to
+understand it's an RSpec output file. You load the template by invoking `require
+rspec/illustrate/yard` and you import it by giving it to YARD as a normal input
+file. Add the following to your `Rakefile`:
+
+```ruby
+require 'yard'
+require 'rspec/illustrate/yard'
+YARD::Rake::YardocTask.new(:doc) do |t|
+    t.files   = ['lib/**/*.rb', 'doc/api.rspec']
+end
+task :doc => [:spec]
+```
+
+You can also include it as an extra file if you want to view it as a complete
+test report (it is HTML after all). Simply add it to the list of extra files by
+adding it after the `-` sign:
+
+```ruby
+require 'yard'
+require 'rspec/illustrate/yard'
+YARD::Rake::YardocTask.new(:doc) do |t|
+    t.files   = ['lib/**/*.rb', 'doc/api.rspec', '-', 'doc/api.rspec']
+end
+task :doc => [:spec]
+```
+
 
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To
-release a new version, update the version number in `version.rb`, and then run
-`bundle exec rake release` to create a git tag for the version, push git commits
+To install this gem onto your local machine, run `rake install`. To release a
+new version, update the version number in `version.rb`, and then run `rake
+release` to create a git tag for the version, push git commits
 and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing

data/Rakefile

@@ -1,15 +1,25 @@
 require "bundler/gem_tasks"
+require 'rake/clean'
 Bundler.setup
 Bundler::GemHelper.install_tasks
 
 require "rspec/core/rake_task"
+desc "Execute RSpec and create a test report at ./doc/api.rspec."
 RSpec::Core::RakeTask.new(:spec) do |t|
-  t.rspec_opts = "--format RSpec::Formatters::IllustratedDocumentationFormatter"
+  t.rspec_opts = "--format RSpec::Formatters::YARD --out ./doc/api.rspec"
 end
 
-RSpec::Core::RakeTask.new(:html) do |t|
-  t.rspec_opts = "--format RSpec::Formatters::IllustratedHtmlFormatter --out ./doc/specs.html"
+require 'yard'
+require 'rspec/illustrate/yard'
+desc "Create documentation."
+YARD::Rake::YardocTask.new(:doc) do |t|
+    t.files   = ['lib/**/*.rb', 'doc/api.rspec', '-', 'doc/api.rspec']
 end
+CLEAN.include("doc")
+CLEAN.include(".yardoc")
+task :doc => [:spec]
 
-task :test => :spec
-task :default => :spec
+desc "Execute tests."
+RSpec::Core::RakeTask.new(:test)
+
+task :default => :test

data/lib/rspec/formatters/illustrated_documentation_formatter.rb

@@ -16,7 +16,7 @@ RSpec.configure do |c|
                   label = illustration.has_key?(:label) ?
                     "--- #{illustration[:label].to_s} ---\n" : ""
 
-                  return label << illustration[:content].to_s
+                  return label << illustration[:text].to_s
                 })
 end
 

data/lib/rspec/formatters/illustrated_html_formatter.rb

@@ -10,11 +10,10 @@ RSpec.configure do |c|
                     html << "<span>#{illustration[:label].to_s}</span>"
                   end
 
-                  content = illustration[:content]
-                  if content.respond_to?(:to_html) then
-                    html << content.to_html
+                  if illustration[:html] then
+                    html << illustration[:html]
                   else
-                    html << "<pre>#{content.to_s}</pre>"
+                    html << "<pre>#{illustration[:text]}</pre>"
                   end
 
                   return html << "</dd>"

data/lib/rspec/formatters/yard.rb

@@ -0,0 +1,153 @@
+require 'rspec/formatters/illustration_formatter'
+require 'rexml/document'
+
+RSpec.configure do |c|
+  c.add_setting(:title, :default => "RSpec results")
+end
+
+module RSpec
+  module Formatters
+
+    # An RSpec output formatter that writes in a specific HTML format that can
+    # be imported by the YARD template. The output can also be viewed as a
+    # stand-alone test report.
+    class YARD
+      include RSpec::Formatters
+
+      # @return [String] the path to the CSS file in the YARD-template, which
+      #                  will be imported into the header so the output HTML can
+      #                  be viewed as a stand-alone document.
+      CSS_FILE = File.join(File.dirname(__FILE__), '..','..','..',
+                           'yard-template', 'default', 'fulldoc', 'html', 'css', 'rspec.css')
+
+      RSpec::Core::Formatters.register self, :example_passed, :example_pending,
+        :example_failed, :stop
+
+      def initialize(output)
+        @output = output
+        @document = REXML::Document.new("<!DOCTYPE html>")
+
+        html = @document.add_element("html")
+        head = html.add_element("head")
+        head.add_element("style").text = IO.read(CSS_FILE)
+        @body = html.add_element("body")
+      end
+
+      # Called by RSpec for each example that passes.
+      # @param passed [RSpec::Core::Notifications::ExampleNotification]
+      def example_passed(passed)
+        node = xml_node_for_notification(passed, :show_when_passed)
+        node.attributes["class"] = "rspec_example_passed"
+      end
+
+      # Called by RSpec for each example that is pending.
+      # @param pending [RSpec::Core::Notifications::ExampleNotification]
+      def example_pending(pending)
+        node = xml_node_for_notification(pending, :show_when_pending)
+        node.attributes["class"] = "rspec_example_pending"
+      end
+
+      # Called by RSpec for each example that failes.
+      # @param failure [RSpec::Core::Notifications::FailedExampleNotification]
+      def example_failed(failure)
+        node = xml_node_for_notification(failure, :show_when_pending)
+        node.attributes["class"] = "rspec_example_failed"
+        node.add_element("exception").text = failure.exception.message
+        node.add_element("backtrace").text = failure.formatted_backtrace.join("\n")
+      end
+
+      # Called by RSpec when the test suite is complete.
+      # @param notification [RSpec::Core::Notifications::ExamplesNotification]
+      def stop(notification)
+        @document.elements["html/head"].add_element("title").text =
+          RSpec.configuration.title
+        @document.write @output
+      end
+
+      private
+
+      # @param notification[RSpec::Core::Notifications:ExampleNotification]
+      # @return [REXML::Element] a new XML node that corresponds to the specific example.
+      def xml_node_for_notification(notification, filter_key)
+        example = notification.example
+        node = xml_node_for_example_group(example.example_group).add_element("div")
+        node.add_element("p", {'class'=>'rspec_example_paragraph'}).text = example.description
+
+        filter(illustrations_of(notification), filter_key).each{|illustration|
+          node.add_element(node_for_illustration(illustration))
+        }
+
+        node
+      end
+
+      # Creates a <div> node for the given illustration.
+      # @param illustration [Hash] the illustration.
+      # @return [REXML::Element] the XML node for the illustration.
+      def node_for_illustration(illustration)
+        node = REXML::Element.new("div")
+        node.add_attribute('class', 'rspec_illustration')
+
+        if label = illustration[:label] then
+          node.add_element("p", {'class'=>'rspec_illustration_label'}).text = label
+        end
+
+        if illustration.has_key?(:html) then
+          node.add_element(REXML::Text.new(illustration[:html], true, nil, true))
+        else
+          node.add_element("pre", {'class'=>'rspec_illustration_content'}).text =
+            REXML::Text.new(illustration[:text], true, nil, true)
+        end
+
+        node
+      end
+
+      # @param example_group [RSpec::Core::ExampleGroup]
+      # @return [REXML::Element] the XML node that corresponds to the specific example group,
+      #                          which will be created if it doesn't exist.
+      def xml_node_for_example_group(example_group)
+        node = @body
+
+        path = example_group.parent_groups.reverse
+        if example_group.described_class then
+          path = path.drop_while{|group|
+            group.described_class != example_group.described_class
+          }
+
+          # use the class/module description as the YARD specific CodeObject id
+          codeobject_id = path.shift.description
+
+          # merge root with first element if it is a method.
+          if path.size >= 1 && (path.first.description.start_with?('#')  ||
+                                path.first.description.start_with?('.')) then
+            codeobject_id = "#{codeobject_id}#{path.shift.description}"
+          end
+
+          # create first node with YARD-specific 'CodeObject' path as id.
+          node = xml_child_node_for_group(codeobject_id, codeobject_id, @body)
+        end
+
+        path.inject(node){|node, group|
+          xml_child_node_for_group(group.name, group.description, node)
+        }
+      end
+
+
+      # @param id [String] the id of the node.
+      # @param caption [String] the description of the node.
+      # @param parent [REXML::Element] the parent node to search within.
+      # @return [REXML::Element] the xml child node with the id and caption, which will be
+      #                          created if it doesn't exist.
+      def xml_child_node_for_group(id, caption, parent=@body)
+        child_node = parent.elements["div[@id='rspec_#{id}']"]
+        return child_node.elements["div[@class='rspec_example_group_children']"] if child_node
+
+        child_node = parent.add_element "div", {'id' => "rspec_#{id}",
+                                                'class'=>"rspec_example_group"}
+        child_node.add_element("div", {'class'=>'rspec_example_group_title'}).text = caption
+        child_node.add_element("div", {'class'=>'rspec_example_group_children'})
+      end
+
+    end
+
+  end
+end

data/lib/rspec/illustrate/version.rb

@@ -1,6 +1,6 @@
 module RSpec
   module Illustrate
     # The version used by gemspec
-    VERSION = "0.1.3"
+    VERSION = "0.2.0"
   end
 end

data/lib/rspec/illustrate/yard.rb

@@ -0,0 +1,55 @@
+
+# Register the template
+YARD::Templates::Engine.register_template_path File.join(File.dirname(__FILE__), '..', '..', '..', 'yard-template')
+# Make sure *.rspec files are treated as HTML files if they are included as
+# extra files (like test reports and such).
+YARD::Templates::Helpers::MarkupHelper::MARKUP_EXTENSIONS[:html] << "rspec"
+
+require 'rspec/illustrate/version'
+require 'rexml/document'
+
+module YARD
+  module Parser
+    # Parses the output from the RSpec::Illustrate::YARD formatter (which is valid
+    # html) and inserts the nodes into the corresponding CodeObject.
+    class RSpecParser < YARD::Parser::Base
+
+      def initialize(source, filename)
+        @source = source
+      end
+
+      # @see YARD::Parser::Base#parse
+      def parse
+        document = REXML::Document.new(@source)
+        document.elements.each("html/body/div") {|element|
+          if (path = element.attributes["id"].sub(/^rspec_/, '')) then
+            if codeobject = YARD::Registry.at(path) then
+              # only grab the <div> that contains the child elements, and omit
+              # caption since we already gave a Specification header.
+              examples = element.elements["div[@class='rspec_example_group_children']"]
+              (codeobject[:rspec] ||= []).concat(examples.to_a)
+            else
+              log.warn "Could not find code object for #{path}, adding it to top level namespace."
+              (YARD::Registry.root[:rspec] ||= []).concat(element.to_a)
+            end
+          end
+        }
+        self
+      end
+
+      # @see YARD::Parser::Base#tokenize
+      def tokenize
+        []
+      end
+
+      # @see YARD::Parser::Base#enumerator
+      def enumerator
+        nil
+      end
+    end
+  end
+end
+
+# Register the parser so YARD knows how to handle *.rspec files.
+YARD::Parser::SourceParser.register_parser_type(:rspec_parser, YARD::Parser::RSpecParser, 'rspec')
+

data/lib/rspec/illustrate.rb

@@ -12,7 +12,7 @@ module RSpec
     # @param args [Array<Hash, Symbol>] Additional options.
     # @return The given illustration object.
     def illustrate(content, *args)
-      illustration = { :content => content,
+      illustration = { :text => content,
                        :show_when_passed  => true,
                        :show_when_failed => true,
                        :show_when_pending => true }

data/rspec-illustrate.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
   spec.email         = ["erik@erisc.se"]
 
   spec.summary       = %q{RSpec extension gem for including illustrative objects in your specs.}
-  spec.description   = %q{A plugin to RSpec that allows you to define illustrative objects in your examples that will be forwarded to the output formatter. This will allow your output spec to become more readable, illustrative, and explanatory.}
+  spec.description   = %q{A plugin to RSpec and YARD that allows you to define illustrative objects in your examples that will be forwarded to the output formatter. The results can be imported into YARD, which makes your generated specs and documentation more readable, illustrative, and explanatory.}
   spec.homepage      = "https://github.com/ErikSchlyter/rspec-illustrate"
   spec.license       = "MIT"
 
@@ -18,8 +18,10 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.required_ruby_version = '>= 1.9.3'
-  spec.add_dependency 'rspec-core', '~> 3.2.1'
-  spec.add_dependency 'rspec-expectations', '~> 3.2.0'
+  spec.add_dependency 'rspec-core', '~> 3.2'
+  spec.add_dependency 'rspec-expectations', '~> 3.2'
   spec.add_development_dependency "bundler", "~> 1.8"
   spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "yard", "~>  0.8"
+  spec.add_development_dependency "redcarpet", "~>  3.2"
 end

data/yard-template/default/fulldoc/html/css/rspec.css

@@ -0,0 +1,50 @@
+.rspec_example_group {
+}
+
+.rspec_example_group_title {
+  padding: 0px 0px 3px 7px;
+  margin: 3px 0px 3px 0px;
+}
+
+.rspec_example_group_children {
+  padding: 0px 0px 0px 0px;
+  margin: 3px 0px 10px 20px;
+  border-left: lightgrey dotted 1px;
+}
+
+.rspec_example_passed, .rspec_example_failed, .rspec_example_pending {
+  padding: 2px 0px 2px 7px;
+  margin: 0px 0px 1px 0px;
+}
+
+.rspec_example_passed {
+  background-color:#E0FFE0;
+}
+
+.rspec_example_pending {
+  background-color:#FFFFE0;
+}
+
+.rspec_example_failed {
+  background-color:#FFA0A0;
+}
+
+.rspec_example_paragraph {
+  margin:0;
+}
+
+.rspec_illustration {
+  margin: 10px 0px 0px 24px;
+}
+
+.rspec_illustration_label {
+  font-style: italic;
+  margin: 0px 0px 0px 0px;
+}
+
+.rspec_illustration_content {
+  margin: 7px 7px 7px 0px;
+  padding: 4px;
+  background-color: rgba(255, 255, 255, 0.5);
+  border: rgba(0, 0, 0, 0.1) solid 1px;
+}

data/yard-template/default/fulldoc/html/setup.rb

@@ -0,0 +1,15 @@
+def init
+  options.files.each{|file|
+    if file.filename.end_with?('.rspec') then
+      document = REXML::Document.new(File.new(file.filename))
+
+      if title = document.elements["html/head/title"] then
+        file.attributes[:title] = title.text
+      end
+      if body = document.elements["html/body"] then
+        file.contents = body.to_s
+      end
+    end
+  }
+  super
+end

data/yard-template/default/layout/html/footer.erb

@@ -0,0 +1,8 @@
+<div id="footer">
+  Generated on <%= Time.now.strftime("%c") %> by
+  <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  <%= YARD::VERSION %>, using
+  <a href="https://github.com/ErikSchlyter/rspec-illustrate" target="_parent">rspec-illustrate</a>
+  <%= RSpec::Illustrate::VERSION %>
+  (ruby-<%= RUBY_VERSION %>).
+</div>

data/yard-template/default/layout/html/setup.rb

@@ -0,0 +1,5 @@
+
+def stylesheets
+  super + %w(css/rspec.css)
+end
+

data/yard-template/default/method_details/html/setup.rb

@@ -0,0 +1,6 @@
+def init
+  super
+  sections.last.place(:specs).before(:source)
+end
+
+

data/yard-template/default/method_details/html/specs.erb

@@ -0,0 +1,6 @@
+<% if object[:rspec] && !object[:rspec].empty? %>
+<div class="tags">
+  <p class="tag_title">Specifications:</p>
+  <%= object[:rspec].collect{|example| example.to_s}.join %>
+</div>
+<% end %>

data/yard-template/default/module/html/setup.rb

@@ -0,0 +1,4 @@
+def init
+  super
+  sections.place(:specs).after(:children)
+end

data/yard-template/default/module/html/specs.erb

@@ -0,0 +1,4 @@
+<% if object[:rspec] && !object[:rspec].empty? %>
+  <h2>Specifications</h2>
+  <%= object[:rspec].collect{|example| example.to_s}.join %>
+<% end %>

metadata

@@ -1,90 +1,110 @@
 --- !ruby/object:Gem::Specification
 name: rspec-illustrate
 version: !ruby/object:Gem::Version
-  version: 0.1.3
-  prerelease: 
+  version: 0.2.0
 platform: ruby
 authors:
 - Erik Schlyter
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-03-30 00:00:00.000000000 Z
+date: 2015-05-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec-core
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.2.1
+        version: '3.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.2.1
+        version: '3.2'
 - !ruby/object:Gem::Dependency
   name: rspec-expectations
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.2.0
+        version: '3.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.2.0
+        version: '3.2'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.8'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.8'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '10.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '10.0'
-description: A plugin to RSpec that allows you to define illustrative objects in your
-  examples that will be forwarded to the output formatter. This will allow your output
-  spec to become more readable, illustrative, and explanatory.
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+description: A plugin to RSpec and YARD that allows you to define illustrative objects
+  in your examples that will be forwarded to the output formatter. The results can
+  be imported into YARD, which makes your generated specs and documentation more readable,
+  illustrative, and explanatory.
 email:
 - erik@erisc.se
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
+- ".gitignore"
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -94,35 +114,42 @@ files:
 - lib/rspec/formatters/illustrated_html_formatter.rb
 - lib/rspec/formatters/illustrated_json_formatter.rb
 - lib/rspec/formatters/illustration_formatter.rb
+- lib/rspec/formatters/yard.rb
 - lib/rspec/illustrate.rb
 - lib/rspec/illustrate/version.rb
+- lib/rspec/illustrate/yard.rb
 - rspec-illustrate.gemspec
+- yard-template/default/fulldoc/html/css/rspec.css
+- yard-template/default/fulldoc/html/setup.rb
+- yard-template/default/layout/html/footer.erb
+- yard-template/default/layout/html/setup.rb
+- yard-template/default/method_details/html/setup.rb
+- yard-template/default/method_details/html/specs.erb
+- yard-template/default/module/html/setup.rb
+- yard-template/default/module/html/specs.erb
 homepage: https://github.com/ErikSchlyter/rspec-illustrate
 licenses:
 - MIT
+metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: 1.9.3
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: 3602209029501457242
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.23
+rubygems_version: 2.2.2
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: RSpec extension gem for including illustrative objects in your specs.
 test_files: []
+has_rdoc: