yard-rspec_examples 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 601f363204ebbf3d59050eab358312982cefc6fa
+  data.tar.gz: 68010e9a097bed8711e97f487654be151c63f515
+SHA512:
+  metadata.gz: 59af946589cc352e1e6c001b1fc7b579772682680cbedf281d5b5828573a52d510430ebe5a02c7ec8ee0b098a570fcb5f569d6e609cd7616b5369a36b56d8620
+  data.tar.gz: 38d4807e9bf351ba80f957351883948345f439c62c167bcb4d1556eb738dd51c41a6b64cc5e11cda0d036b4b616e62d52816f1e9adefd8fee62d4cf75faf5fb6

data/.document

@@ -0,0 +1,4 @@
+lib/**/*.rb
+spec/**/*.rb
+-
+LICENSE.txt

data/.gitignore

@@ -0,0 +1,4 @@
+doc
+.yardoc
+Gemfile.lock
+.ruby-version

data/.rspec

@@ -0,0 +1 @@
+--color

data/.yardopts

@@ -0,0 +1 @@
+--plugin yard-rspec_examples

data/Gemfile

@@ -0,0 +1,8 @@
+source "http://rubygems.org"
+
+gemspec
+
+group :development do
+  gem "rspec"
+  gem "yard"
+end

data/Gemfile.lock

@@ -0,0 +1,35 @@
+PATH
+  remote: .
+  specs:
+    yard-rspec_examples (0.0.1)
+      yard
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.2.5)
+    rspec (3.4.0)
+      rspec-core (~> 3.4.0)
+      rspec-expectations (~> 3.4.0)
+      rspec-mocks (~> 3.4.0)
+    rspec-core (3.4.1)
+      rspec-support (~> 3.4.0)
+    rspec-expectations (3.4.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.4.0)
+    rspec-mocks (3.4.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.4.0)
+    rspec-support (3.4.1)
+    yard (0.8.7.6)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  rspec
+  yard
+  yard-rspec_examples!
+
+BUNDLED WITH
+   1.10.6

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Jose Fernandez (magec)
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,75 @@
+= yard-rspec_examples
+
+Yard plugin to include examples in the generated doc through rspec
+
+== Installation
+
+In order to install it you just have to install it gem from gemcutter
+
+  gem install yard-rspec_examples
+
+== Description
+
+This plugin simply includes an example tag and recreates it with the source code that corresponds
+to the first example included in the describe blocks below.
+This have to be defined inside a describe block called "#method_name" that, in turn,
+has to be defined in a describe block with the class name, i.e. the regular way people use rspec when testing objects.
+
+So, for example,
+
+Given this source code:
+
+  class Foo
+    ## 
+    # This is a foo method with an example
+    # @rspec_example
+    def foo_method
+    end
+  end
+
+And this spec:
+
+  describe Foo do
+    describe "#foo_method" do 
+      it "works this way" do
+        this = "is"
+        # The code that will be included in the example
+      end
+    end
+  end
+
+A result like this is to be expected
+  class Foo
+    ## 
+    # This is a foo method with an example
+    # @example
+    #   this = "is"
+    #   # The code that will be included in the example
+    def foo_method
+    end
+  end
+
+Another usage is to pass the example's name to the tag:
+
+  class Foo
+    ##
+    # This is a foo method with an example
+    # @rspec_example works this way
+    def foo_method
+    end
+  end
+
+
+
+
+== Using it
+
+In order to use it, you just have to add the --plugin param plus yours
+
+  yardoc --plugin yar-rspec_examples [OPTS]
+
+
+== Copyright
+Copyright (c) 2011 Jose Fernandez (magec). See LICENSE.txt for
+further details.
+

data/Rakefile

@@ -0,0 +1,18 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.rspec_opts = "--color"
+end
+
+require 'rubygems'
+
+require 'rake'

data/lib/yard/rspec_examples/describe_handler.rb

@@ -0,0 +1,36 @@
+module YARD
+  module RSpecExamples
+    # Handler used to inspect the rspec describe call
+    # used, to catch the class describe declarations and method declarations
+    class RSpecDescribeHandler < YARD::Handlers::Ruby::Base
+
+      handles method_call(:describe)
+
+      def process
+        param = statement.parameters.first
+
+        subject = nil
+
+        # A class is being declared
+        if param.type == :var_ref && param.children.first.type == :const
+          subject = param.children.first.source
+        end
+
+        # A class is being declared (with a nested name)
+        if param.type == :const_path_ref
+          subject = param.children.map { |i| i.source }.join("::")
+        end
+
+        # A method is being declared
+        if param.type == :string_literal && param.source =~ /^"#/
+          subject = param.source.delete('"|\ ')
+        end
+
+        ParserTrace.path.push(subject.dup) if subject
+        parse_block(statement.last.last)
+        ParserTrace.path.pop if subject
+      end
+    end
+  end
+end
+

data/lib/yard/rspec_examples/it_handler.rb

@@ -0,0 +1,16 @@
+module YARD
+  module RSpecExamples
+    # Handler that will set up the method <-> example map
+    class ItHandler < YARD::Handlers::Ruby::Base
+
+      handles method_call(:it)
+
+      def process
+        it_description = statement.parameters.source[1...-1]
+        rspec_path_string = ParserTrace.path.dup.push(it_description).join(' ')
+        #TODO: indentation depends on level of test indents.
+        RSpecExampleRegistry.example_map[rspec_path_string] = statement.block.last.source.gsub("\n      ", "\n")
+      end
+    end
+  end
+end

data/lib/yard/rspec_examples/module_handler.rb

@@ -0,0 +1,34 @@
+module YARD
+  module RSpecExamples
+    class ModuleHandler < YARD::Handlers::Ruby::Base
+      handles :module
+
+      def process
+        # param = statement.parameters.first
+        #
+        # subject = nil
+        #
+        # # A class is being declared
+        # if param.type == :var_ref && param.children.first.type == :const
+        #   subject = param.children.first.source
+        # end
+        #
+        # # A class is being declared (with a nested name)
+        # if param.type == :const_path_ref
+        #   subject = param.children.map { |i| i.source }.join("::")
+        # end
+        #
+        # # A method is being declared
+        # if param.type == :string_literal && param.source =~ /^"#/
+        #   subject = param.source.delete('"|\ ')
+        # end
+        #
+        #TODO: probably thave to strip namespace from the module
+        ParserTrace.path.push(statement.module_name.path)
+        parse_block(statement.last.last)
+        ParserTrace.path.pop
+      end
+
+    end
+  end
+end

data/lib/yard/rspec_examples/parser_trace.rb

@@ -0,0 +1,10 @@
+module YARD
+  module RSpecExamples
+    class ParserTrace
+      def self.path
+        @path ||= []
+      end
+    end
+  end
+end
+

data/lib/yard/rspec_examples/version.rb

@@ -0,0 +1,5 @@
+module YARD
+  module RSpecExamples
+    VERSION = '0.0.1'
+  end
+end

data/lib/yard-rspec_examples.rb

@@ -0,0 +1,54 @@
+# -*- coding: utf-8 -*-
+require 'yard'
+require 'yard/rspec_examples/it_handler'
+require 'yard/rspec_examples/module_handler'
+require 'yard/rspec_examples/describe_handler'
+require 'yard/rspec_examples/parser_trace'
+
+##
+# This class will hold a map that associates the method descriptions with its source code
+class RSpecExampleRegistry
+  def self.example_map
+    @example_map ||= {}
+  end
+end
+
+module YARD
+  module Tags
+    ##
+    # A new type of tags has to be used cause we need to intercept the
+    # text call and generate its contents (in generation time, after everything was parsed)
+    class RSpecExampleTag < Tag
+      def text
+        # for now, we just handle case where describes are derived from the context
+        example_description = rspec_description(object).gsub(/^::/,'').gsub(/ ::/, ' ')
+        example_description += " #{name}" unless name.empty?
+        key = RSpecExampleRegistry.example_map.keys.detect{|k| k.include?(example_description)}
+        puts "[warn] Could not find example '#{example_description}'" unless key
+        @text = RSpecExampleRegistry.example_map[key]
+      end
+
+      private
+      def rspec_description(object)
+        case object
+        when CodeObjects::RootObject
+          ""
+        when CodeObjects::MethodObject
+          "#{rspec_description(object.namespace)} ##{object.name}"
+        when CodeObjects::ClassObject
+          "#{rspec_description(object.namespace)}::#{object.name}"
+        when CodeObjects::ModuleObject
+          "#{rspec_description(object.namespace)}#{object.name} "
+        end
+      end
+    end
+
+    class DefaultFactory
+      def parse_tag_with_rspec_example_tag(tagname, text)
+        RSpecExampleTag.new(:example, "", [], text)
+      end
+    end
+  end
+end
+
+YARD::Tags::Library.define_tag("Rspec Example", :rspec_example, :with_rspec_example_tag)

data/spec/fixtures/example_file.rb

@@ -0,0 +1,37 @@
+class Foo
+  ## 
+  # This is a foo method with an example
+  # @rspec_example
+  # @rspec_example also supports this
+  def foo_method
+  end
+end
+
+class Foo
+  class Bar
+    ##
+    # This is a class nested example
+    # @rspec_example
+    def bar_method
+    end
+  end
+end
+
+module My
+  class Nested
+    class Class
+      ##
+      # This is a module/class nested example
+      # @rspec_example
+      def nested_method
+      end
+    end
+  end
+end
+
+class InvalidClass
+  # tada
+  # @rspec_example invalid
+  def some_method
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,6 @@
+require 'yard-rspec_examples'
+require 'fixtures/example_file'
+
+RSpec.configure do |config|
+  
+end

data/spec/yard-rspec_examples_spec.rb

@@ -0,0 +1,99 @@
+require 'spec_helper'
+require 'yard'
+EXAMPLE_DOC_DIR=[File.expand_path(File.dirname(__FILE__) + "/fixtures/*.rb"), File.expand_path(File.dirname(__FILE__) + "/*.rb")]
+
+OPTIONS = {
+  :format => :html,
+  :template => :default,
+  :markup => :rdoc,
+  :serializer => YARD::Serializers::FileSystemSerializer.new,
+  :default_return => "Object",
+  :hide_void_return => false,
+  :no_highlight => false,
+  :files => []
+}
+
+describe "Using the rspec_example tag in the method comment" do
+  before(:each) do
+    YARD.parse(EXAMPLE_DOC_DIR)
+    foo = YARD::Registry.all(:class).find { |i| i.to_s == "Foo" }
+    @class_foo_output = YARD::Templates::Engine.render(OPTIONS.merge(:object => foo))
+    bar = YARD::Registry.all(:class).find { |i| i.to_s == "Foo::Bar" }
+    @class_bar_output = YARD::Templates::Engine.render(OPTIONS.merge(:object => bar))
+    nested_class = YARD::Registry.all(:class).find { |i| i.to_s == "My::Nested::Class" }
+    @nested_class_output = YARD::Templates::Engine.render(OPTIONS.merge(:object => nested_class))
+  end
+
+  it "displays warning on unfound example" do
+    expect do
+      invalid_class = YARD::Registry.all(:class).find { |i| i.to_s == "InvalidClass" }
+      @invalid_class_output = YARD::Templates::Engine.render(OPTIONS.merge(:object => invalid_class))
+    end.to output("[warn] Could not find example 'InvalidClass #some_method invalid'\n").to_stdout
+  end
+
+  it "creates an example tag in the registry" do
+    expect(@class_foo_output).to match /Examples:/
+  end
+
+  it "outputs the source code of the example of a method that reads \"works this way\" " do
+    expect(@class_foo_output).to match /this/
+  end
+
+  it "includes the comments in the example as well" do
+    # TODO: comments as first line get stripped away right now.
+    expect(@class_foo_output).to match /With some comments/
+  end
+
+  it "works with nested classes" do
+    expect(@class_bar_output).to match /nested_class/
+  end
+
+  it "works with module/class/classs nestes classes" do
+    expect(@nested_class_output).to match /super_nested_class/
+  end
+
+  it "includes named examples" do
+    expect(@class_foo_output).to include CGI.escape_html("comment for 'also support this' it")
+  end
+end
+
+# A bit of a hack, this is the spec that is going to be used as fixture for the plugin
+describe Foo do
+  describe "#foo_method" do
+    it "works this way" do
+      this = "is"
+      just = "example code"
+      # With some comments
+      [1, 2, 3].each do |i|
+        i
+      end
+    end
+
+    it "also supports this" do
+      0 + 0
+      # comment for 'also support this' it
+      1 + 2
+      # kilo
+      4 + 3
+    end
+  end
+end
+
+
+describe Foo::Bar do
+  describe "#bar_method" do
+    it "works this way" do
+      nested_class = nil
+    end
+  end
+end
+
+module My
+  describe Nested::Class do
+    describe "#nested_method" do
+      it "works this way" do
+        super_nested_class = nil
+      end
+    end
+  end
+end

data/yard-rspec_examples.gemspec

@@ -0,0 +1,19 @@
+$LOAD_PATH.unshift 'lib'
+require 'yard/rspec_examples/version'
+
+Gem::Specification.new do |s|
+  s.name          = 'yard-rspec_examples'
+  s.version       = YARD::RSpecExamples::VERSION
+  s.authors       = [ 'Bert Bruynooghe', 'Jose Fernandez (magec)' ]
+  s.email         = [ 'info@up-nxt.com' ]
+  s.homepage      = 'https://github.com/UP-nxt/yard-rspec_examples'
+  s.summary       = 'Yard plugin to include RSpec examples in documentation'
+  s.description   = 'Yard plugin to include RSpec examples in documentation'
+
+  s.files         = `git ls-files`.split($/)
+  s.executables   = s.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  s.test_files    = s.files.grep(%r{^(test|spec|features)/})
+  s.require_paths = [ 'lib' ]
+
+  s.add_dependency 'yard'
+end

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: yard-rspec_examples
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Bert Bruynooghe
+- Jose Fernandez (magec)
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-01-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Yard plugin to include RSpec examples in documentation
+email:
+- info@up-nxt.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".document"
+- ".gitignore"
+- ".rspec"
+- ".yardopts"
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.rdoc
+- Rakefile
+- lib/yard-rspec_examples.rb
+- lib/yard/rspec_examples/describe_handler.rb
+- lib/yard/rspec_examples/it_handler.rb
+- lib/yard/rspec_examples/module_handler.rb
+- lib/yard/rspec_examples/parser_trace.rb
+- lib/yard/rspec_examples/version.rb
+- spec/fixtures/example_file.rb
+- spec/spec_helper.rb
+- spec/yard-rspec_examples_spec.rb
+- yard-rspec_examples.gemspec
+homepage: https://github.com/UP-nxt/yard-rspec_examples
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: Yard plugin to include RSpec examples in documentation
+test_files:
+- spec/fixtures/example_file.rb
+- spec/spec_helper.rb
+- spec/yard-rspec_examples_spec.rb
+has_rdoc: