yard-examples-from-rspec 0.0.1

Sign up to get free protection for your applications and to get access to all the features.
@@ -0,0 +1,5 @@
1
+ lib/**/*.rb
2
+ bin/*
3
+ -
4
+ features/**/*.feature
5
+ LICENSE.txt
data/.rspec ADDED
@@ -0,0 +1 @@
1
+ --color
data/Gemfile ADDED
@@ -0,0 +1,14 @@
1
+ source "http://rubygems.org"
2
+ # Add dependencies required to use your gem here.
3
+ # Example:
4
+ # gem "activesupport", ">= 2.3.5"
5
+
6
+ # Add dependencies to develop your gem here.
7
+ # Include everything needed to run rake, tests, features, etc.
8
+ group :development do
9
+ gem "rspec", "~> 2.3.0"
10
+ gem "yard", "~> 0.6.0"
11
+ gem "bundler", "~> 1.0.0"
12
+ gem "jeweler", "~> 1.5.2"
13
+ gem "rcov", ">= 0"
14
+ end
@@ -0,0 +1,30 @@
1
+ GEM
2
+ remote: http://rubygems.org/
3
+ specs:
4
+ diff-lcs (1.1.2)
5
+ git (1.2.5)
6
+ jeweler (1.5.2)
7
+ bundler (~> 1.0.0)
8
+ git (>= 1.2.5)
9
+ rake
10
+ rake (0.8.7)
11
+ rcov (0.9.9)
12
+ rspec (2.3.0)
13
+ rspec-core (~> 2.3.0)
14
+ rspec-expectations (~> 2.3.0)
15
+ rspec-mocks (~> 2.3.0)
16
+ rspec-core (2.3.1)
17
+ rspec-expectations (2.3.0)
18
+ diff-lcs (~> 1.1.2)
19
+ rspec-mocks (2.3.0)
20
+ yard (0.6.4)
21
+
22
+ PLATFORMS
23
+ ruby
24
+
25
+ DEPENDENCIES
26
+ bundler (~> 1.0.0)
27
+ jeweler (~> 1.5.2)
28
+ rcov
29
+ rspec (~> 2.3.0)
30
+ yard (~> 0.6.0)
@@ -0,0 +1,20 @@
1
+ Copyright (c) 2010 Jose Fernandez (magec)
2
+
3
+ Permission is hereby granted, free of charge, to any person obtaining
4
+ a copy of this software and associated documentation files (the
5
+ "Software"), to deal in the Software without restriction, including
6
+ without limitation the rights to use, copy, modify, merge, publish,
7
+ distribute, sublicense, and/or sell copies of the Software, and to
8
+ permit persons to whom the Software is furnished to do so, subject to
9
+ the following conditions:
10
+
11
+ The above copyright notice and this permission notice shall be
12
+ included in all copies or substantial portions of the Software.
13
+
14
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
15
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
17
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
18
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
19
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
20
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
@@ -0,0 +1,69 @@
1
+ = yard-examples-from-rspec
2
+
3
+ Yard plugin to include examples in the generated doc through rspec
4
+
5
+ == Installation
6
+
7
+ I order to install it you just have to install it gem from gemcutter
8
+
9
+ gem install yard-examples-from-rspec
10
+
11
+ == Description
12
+
13
+ This plugin simply includes an example tag and recreates it with the source code that corresponds to an example called "works this way". 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.
14
+
15
+ So, for example,
16
+
17
+ Given this source code:
18
+
19
+ class Foo
20
+ ##
21
+ # This is a foo method with an example
22
+ # @rspec_example
23
+ def foo_method
24
+ end
25
+ end
26
+
27
+ And this spec:
28
+
29
+ describe Foo::Bar do
30
+ describe "#bar_method" do
31
+ it "works this way" do
32
+ this = "is"
33
+ # The code that will be included in the example
34
+ end
35
+ end
36
+ end
37
+
38
+ A result like this is to be expected
39
+ class Foo
40
+ ##
41
+ # This is a foo method with an example
42
+ # @example
43
+ # this = "is"
44
+ # # The code that will be included in the example
45
+ def foo_method
46
+ end
47
+ end
48
+
49
+ == Using it
50
+
51
+ In order to use it, you just have to add the --plugin param plus yours
52
+
53
+ yardoc --plugin examples-from-rspec [OPTS]
54
+
55
+ == Contributing to yard-examples-from-rspec
56
+
57
+ * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
58
+ * Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
59
+ * Fork the project
60
+ * Start a feature/bugfix branch
61
+ * Commit and push until you are happy with your contribution
62
+ * Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
63
+ * Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
64
+
65
+ == Copyright
66
+
67
+ Copyright (c) 2011 Jose Fernandez (magec). See LICENSE.txt for
68
+ further details.
69
+
@@ -0,0 +1,44 @@
1
+ require 'rubygems'
2
+ require 'bundler'
3
+ begin
4
+ Bundler.setup(:default, :development)
5
+ rescue Bundler::BundlerError => e
6
+ $stderr.puts e.message
7
+ $stderr.puts "Run `bundle install` to install missing gems"
8
+ exit e.status_code
9
+ end
10
+ require 'rake'
11
+
12
+ require 'jeweler'
13
+ Jeweler::Tasks.new do |gem|
14
+ # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
15
+ gem.name = "yard-examples-from-rspec"
16
+ gem.homepage = "http://github.com/magec/yard-examples-from-rspec"
17
+ gem.license = "MIT"
18
+ gem.summary = %Q{Yard plugin to include rspec examples in the generated doc }
19
+ gem.description = %Q{Fills up your documentation with examples taken from rspec}
20
+ gem.email = "jfernandezperez@gmail.com"
21
+ gem.authors = ["Jose Fernandez (magec)"]
22
+ gem.add_runtime_dependency "yard", "~> 0.6.0"
23
+ # Include your dependencies below. Runtime dependencies are required when using your gem,
24
+ # and development dependencies are only needed for development (ie running rake tasks, tests, etc)
25
+ # gem.add_runtime_dependency 'jabber4r', '> 0.1'
26
+ # gem.add_development_dependency 'rspec', '> 1.2.3'
27
+ end
28
+ Jeweler::RubygemsDotOrgTasks.new
29
+
30
+ require 'rspec/core'
31
+ require 'rspec/core/rake_task'
32
+ RSpec::Core::RakeTask.new(:spec) do |spec|
33
+ spec.pattern = FileList['spec/**/*_spec.rb']
34
+ end
35
+
36
+ RSpec::Core::RakeTask.new(:rcov) do |spec|
37
+ spec.pattern = 'spec/**/*_spec.rb'
38
+ spec.rcov = true
39
+ end
40
+
41
+ task :default => :spec
42
+
43
+ require 'yard'
44
+ YARD::Rake::YardocTask.new
data/VERSION ADDED
@@ -0,0 +1 @@
1
+ 0.0.1
@@ -0,0 +1,86 @@
1
+ # -*- coding: utf-8 -*-
2
+ require 'yard'
3
+
4
+ ##
5
+ # This class will hold a map that associates the method descriptions with its source code
6
+ class RSpecExampleRegistry
7
+ def self.example_map
8
+ @example_map ||= {}
9
+ end
10
+ end
11
+
12
+ EXAMPLE_MATCHERS = [ "works this way" ]
13
+
14
+ ##
15
+ # Handler that will set up the method <-> example map
16
+ class RSpecItHandler < YARD::Handlers::Ruby::Base
17
+
18
+ handles method_call(:it)
19
+
20
+ def process
21
+ param = statement.parameters.first.jump(:string_content).source
22
+ if param =~ Regexp.union(*EXAMPLE_MATCHERS)
23
+ RSpecExampleRegistry.example_map[RSpecDescribeHandler.current_path] = statement.last.last.source.gsub("\n ","\n")
24
+ end
25
+ end
26
+
27
+ end
28
+
29
+ ##
30
+ # Handler used to inspect the rspec describe call
31
+ # used, to catch the class describe declarations and method declarations
32
+ class RSpecDescribeHandler < YARD::Handlers::Ruby::Base
33
+
34
+ class << self
35
+ attr_accessor :current_class,:current_method
36
+
37
+ def current_path
38
+ return "#{@current_class}##{@current_method}"
39
+ end
40
+
41
+ end
42
+
43
+ handles method_call(:describe)
44
+
45
+ def process
46
+ param = statement.parameters.first
47
+
48
+ # A class is being declared
49
+ if param.type == :var_ref && param.children.first.type == :const
50
+ self.class.current_class = param.children.first.source
51
+ end
52
+
53
+ # A class is being declared (with a nested name)
54
+ if param.type == :const_path_ref
55
+ self.class.current_class = param.children.map{|i| i.source}.join("::")
56
+ end
57
+
58
+ # A method is being declared
59
+ if param.type == :string_literal && param.source =~ /^"#/
60
+ self.class.current_method = param.source.delete('#|"|\ ')
61
+ end
62
+
63
+ parse_block(statement.last.last)
64
+ end
65
+ end
66
+
67
+ module YARD
68
+ module Tags
69
+ ##
70
+ # A new type of tags has to be used cause we need to intercept the
71
+ # text call and generate its contents (in generation time, after everything was parsed)
72
+ class RSpecExampleTag < Tag
73
+ def text
74
+ @text =RSpecExampleRegistry.example_map[object.path]
75
+ end
76
+ end
77
+
78
+ class DefaultFactory
79
+ def parse_tag_with_rspec_example_tag(tagname,text)
80
+ RSpecExampleTag.new(:example,"")
81
+ end
82
+ end
83
+ end
84
+ end
85
+
86
+ YARD::Tags::Library.define_tag("Rspec Example",:rspec_example,:with_rspec_example_tag)
@@ -0,0 +1,32 @@
1
+ class Foo
2
+ ##
3
+ # This is a foo method with an example
4
+ # @rspec_example
5
+ def foo_method
6
+ end
7
+ end
8
+
9
+ class Foo
10
+ class Bar
11
+ ##
12
+ # This is a class nested example
13
+ # @rspec_example
14
+ def bar_method
15
+ end
16
+ end
17
+ end
18
+
19
+ module My
20
+ class Nested
21
+ class Class
22
+ ##
23
+ # This is a module/class nested example
24
+ # @rspec_example
25
+ def nested_method
26
+ end
27
+ end
28
+ end
29
+ end
30
+
31
+
32
+
@@ -0,0 +1,13 @@
1
+ $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
2
+ $LOAD_PATH.unshift(File.dirname(__FILE__))
3
+ require 'rspec'
4
+ require 'yard-examples-from-rspec'
5
+ require 'fixtures/example_file'
6
+
7
+ # Requires supporting files with custom matchers and macros, etc,
8
+ # in ./support/ and its subdirectories.
9
+ Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each {|f| require f}
10
+
11
+ RSpec.configure do |config|
12
+
13
+ end
@@ -0,0 +1,80 @@
1
+ require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
2
+ EXAMPLE_DOC_DIR=[File.expand_path(File.dirname(__FILE__) + "/fixtures/*.rb") , File.expand_path(File.dirname(__FILE__) + "/*.rb") ]
3
+
4
+ OPTIONS = {
5
+ :format => :html,
6
+ :template => :default,
7
+ :markup => :rdoc,
8
+ :serializer => YARD::Serializers::FileSystemSerializer.new,
9
+ :default_return => "Object",
10
+ :hide_void_return => false,
11
+ :no_highlight => false,
12
+ :files => []
13
+ }
14
+
15
+ describe "When we use the rspec_example tag in the method comment" do
16
+ before(:each) do
17
+ YARD.parse(EXAMPLE_DOC_DIR)
18
+ foo = YARD::Registry.all(:class).find {|i| i.to_s == "Foo" }
19
+ @class_foo_output = YARD::Templates::Engine.render(OPTIONS.merge(:object => foo))
20
+ bar = YARD::Registry.all(:class).find {|i| i.to_s == "Foo::Bar" }
21
+ # YARD::Templates::Engine.generate([foo], OPTIONS)
22
+ @class_bar_output = YARD::Templates::Engine.render(OPTIONS.merge(:object => bar))
23
+ nested_class = YARD::Registry.all(:class).find {|i| i.to_s == "My::Nested::Class" }
24
+ @nested_class_output = YARD::Templates::Engine.render(OPTIONS.merge(:object => nested_class))
25
+
26
+ end
27
+
28
+ it "creates an example tag in the registry" do
29
+ @class_foo_output.should match /Examples:/
30
+ end
31
+
32
+ it "outputs the source code of the example of a method that reads \"works this way\" " do
33
+ @class_foo_output.should match /this/
34
+ end
35
+
36
+ it "should include the comments in the example as well" do
37
+ @class_foo_output.should match /With some comments/
38
+ end
39
+
40
+ it "should also work with nested classes" do
41
+ @class_bar_output.should match /nested_class/
42
+ end
43
+
44
+ it "should also work with module/class/classs nestes classes" do
45
+ @nested_class_output.should match /super_nested_class/
46
+ end
47
+
48
+ end
49
+
50
+ # A bit of a hack, this is the spec that is going to be used as fixture for the plugin
51
+ describe Foo do
52
+ describe "#foo_method" do
53
+ it "works this way" do
54
+ this = "is"
55
+ just = "example code"
56
+ # With some comments
57
+ [1,2,3].each do |i|
58
+ i
59
+ end
60
+ end
61
+ end
62
+ end
63
+
64
+
65
+ describe Foo::Bar do
66
+ describe "#bar_method" do
67
+ it "works this way" do
68
+ nested_class = nil
69
+ end
70
+ end
71
+ end
72
+
73
+ describe My::Nested::Class do
74
+ describe "#nested_method" do
75
+ it "works this way" do
76
+ super_nested_class = nil
77
+ end
78
+ end
79
+ end
80
+
metadata ADDED
@@ -0,0 +1,166 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: yard-examples-from-rspec
3
+ version: !ruby/object:Gem::Version
4
+ prerelease: false
5
+ segments:
6
+ - 0
7
+ - 0
8
+ - 1
9
+ version: 0.0.1
10
+ platform: ruby
11
+ authors:
12
+ - Jose Fernandez (magec)
13
+ autorequire:
14
+ bindir: bin
15
+ cert_chain: []
16
+
17
+ date: 2011-01-03 00:00:00 +01:00
18
+ default_executable:
19
+ dependencies:
20
+ - !ruby/object:Gem::Dependency
21
+ name: rspec
22
+ requirement: &id001 !ruby/object:Gem::Requirement
23
+ none: false
24
+ requirements:
25
+ - - ~>
26
+ - !ruby/object:Gem::Version
27
+ segments:
28
+ - 2
29
+ - 3
30
+ - 0
31
+ version: 2.3.0
32
+ type: :development
33
+ prerelease: false
34
+ version_requirements: *id001
35
+ - !ruby/object:Gem::Dependency
36
+ name: yard
37
+ requirement: &id002 !ruby/object:Gem::Requirement
38
+ none: false
39
+ requirements:
40
+ - - ~>
41
+ - !ruby/object:Gem::Version
42
+ segments:
43
+ - 0
44
+ - 6
45
+ - 0
46
+ version: 0.6.0
47
+ type: :development
48
+ prerelease: false
49
+ version_requirements: *id002
50
+ - !ruby/object:Gem::Dependency
51
+ name: bundler
52
+ requirement: &id003 !ruby/object:Gem::Requirement
53
+ none: false
54
+ requirements:
55
+ - - ~>
56
+ - !ruby/object:Gem::Version
57
+ segments:
58
+ - 1
59
+ - 0
60
+ - 0
61
+ version: 1.0.0
62
+ type: :development
63
+ prerelease: false
64
+ version_requirements: *id003
65
+ - !ruby/object:Gem::Dependency
66
+ name: jeweler
67
+ requirement: &id004 !ruby/object:Gem::Requirement
68
+ none: false
69
+ requirements:
70
+ - - ~>
71
+ - !ruby/object:Gem::Version
72
+ segments:
73
+ - 1
74
+ - 5
75
+ - 2
76
+ version: 1.5.2
77
+ type: :development
78
+ prerelease: false
79
+ version_requirements: *id004
80
+ - !ruby/object:Gem::Dependency
81
+ name: rcov
82
+ requirement: &id005 !ruby/object:Gem::Requirement
83
+ none: false
84
+ requirements:
85
+ - - ">="
86
+ - !ruby/object:Gem::Version
87
+ segments:
88
+ - 0
89
+ version: "0"
90
+ type: :development
91
+ prerelease: false
92
+ version_requirements: *id005
93
+ - !ruby/object:Gem::Dependency
94
+ name: yard
95
+ requirement: &id006 !ruby/object:Gem::Requirement
96
+ none: false
97
+ requirements:
98
+ - - ~>
99
+ - !ruby/object:Gem::Version
100
+ segments:
101
+ - 0
102
+ - 6
103
+ - 0
104
+ version: 0.6.0
105
+ type: :runtime
106
+ prerelease: false
107
+ version_requirements: *id006
108
+ description: Fills up your documentation with examples taken from rspec
109
+ email: jfernandezperez@gmail.com
110
+ executables: []
111
+
112
+ extensions: []
113
+
114
+ extra_rdoc_files:
115
+ - LICENSE.txt
116
+ - README.rdoc
117
+ files:
118
+ - .document
119
+ - .rspec
120
+ - Gemfile
121
+ - Gemfile.lock
122
+ - LICENSE.txt
123
+ - README.rdoc
124
+ - Rakefile
125
+ - VERSION
126
+ - lib/yard-examples-from-rspec.rb
127
+ - spec/fixtures/example_file.rb
128
+ - spec/spec_helper.rb
129
+ - spec/yard-examples-from-rspec_spec.rb
130
+ has_rdoc: true
131
+ homepage: http://github.com/magec/yard-examples-from-rspec
132
+ licenses:
133
+ - MIT
134
+ post_install_message:
135
+ rdoc_options: []
136
+
137
+ require_paths:
138
+ - lib
139
+ required_ruby_version: !ruby/object:Gem::Requirement
140
+ none: false
141
+ requirements:
142
+ - - ">="
143
+ - !ruby/object:Gem::Version
144
+ hash: -95287023
145
+ segments:
146
+ - 0
147
+ version: "0"
148
+ required_rubygems_version: !ruby/object:Gem::Requirement
149
+ none: false
150
+ requirements:
151
+ - - ">="
152
+ - !ruby/object:Gem::Version
153
+ segments:
154
+ - 0
155
+ version: "0"
156
+ requirements: []
157
+
158
+ rubyforge_project:
159
+ rubygems_version: 1.3.7
160
+ signing_key:
161
+ specification_version: 3
162
+ summary: Yard plugin to include rspec examples in the generated doc
163
+ test_files:
164
+ - spec/fixtures/example_file.rb
165
+ - spec/spec_helper.rb
166
+ - spec/yard-examples-from-rspec_spec.rb