smashing_docs 0.1.0 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: 51d3931b8339c80e86f365d38579ca206aaec9e6
4
- data.tar.gz: ef9f7460e973252cf1d722423d5b201de50ec238
3
+ metadata.gz: 31bc78abe84edc9c4717b1b0d1c792c23cef3cdc
4
+ data.tar.gz: 8f1dce8a1fd1be5e34512a7ac4c2847142d6881e
5
5
  SHA512:
6
- metadata.gz: d9d6a0a33ee29cdbf5b22ba8b2fbd7235274cb36b4e81b96a4e6af76de8bf72d19f7acf474369c1de77ee2eb245d36ee626c910d785ee13ffb3d7e7d8722c18e
7
- data.tar.gz: 2e8b0895112ea255a09a3cbebed9a747fbdd2a19e4ff7d7864dcb5d1aa9de4f238481119addd7c3c8b2a2a8801e7105ced9ed558f90e361e7d97ecece0dd8c5c
6
+ metadata.gz: 59e40621f291e1b6af8e0cff399de36ef81c0c6ac20e2c41b00c43e6c6b6d64b47c40dab566816ae2eaa659618057a41108fcaad5ac6f60fd5ac86b4b9300778
7
+ data.tar.gz: 1b32b71daeba769df485cd1318da17c877f9444981956df1b7837aac5b06f83b539620a93e3a216ad176735cbe239be8794d4932609669e3ba228dcd573ec55d
data/README.md CHANGED
@@ -26,12 +26,13 @@ Add this to your `rails_helper.rb` It should go outside of other blocks
26
26
  (Do not place it inside the `RSpec.configure` block).
27
27
  ```ruby
28
28
  SmashingDocs.config do |c|
29
- c.template_file = 'spec/template.md.erb'
30
- c.output_file = 'api_docs.md'
29
+ c.template_file = 'smashing_docs/template.md'
30
+ c.output_file = 'smashing_docs/api_docs.md'
31
+ c.run_all = true
31
32
  end
32
33
  ```
33
34
 
34
- Add the following line to `spec_helper.rb` inside the `RSpec.configure` block
35
+ Add the following content to `spec_helper.rb` inside the `RSpec.configure` block
35
36
 
36
37
  `config.after(:suite) { SmashingDocs.finish! }`
37
38
 
@@ -39,30 +40,24 @@ It should look like this
39
40
  ```ruby
40
41
  RSpec.configure do |config|
41
42
  # Existing code
43
+ config.after(:each, type: :controller) do
44
+ SmashingDocs.run!(request, response, true)
45
+ end
42
46
  config.after(:suite) { SmashingDocs.finish! }
43
47
  end
44
48
  ```
45
- #### To run on all controller tests
46
49
 
47
- Add this to your `spec_helper.rb`
50
+ #### To run on only select tests
51
+ Set the `c.run_all` line to `false` in `rails_helper.rb`
48
52
  ```ruby
49
- config.after(:each, type: :controller) do
50
- SmashingDocs.run!(request, response)
53
+ SmashingDocs.config do |c|
54
+ c.template_file = 'smashing_docs/template.md'
55
+ c.output_file = 'smashing_docs/api_docs.md'
56
+ c.run_all = false
51
57
  end
52
58
  ```
53
59
 
54
- The whole file should look like this
55
- ```ruby
56
- RSpec.configure do |config|
57
- # Existing code
58
- config.after(:each, type: :controller) do
59
- SmashingDocs.run!(request, response)
60
- end
61
- config.after(:suite) { SmashingDocs.finish! }
62
- end
63
- ```
64
- #### To run on only select tests
65
- Just add `SmashingDocs.run!(request, response)` to specific tests
60
+ Then just add `SmashingDocs.run!(request, response)` to the tests you want to run
66
61
  ```ruby
67
62
  it "responds with 200" do
68
63
  get :index
@@ -78,47 +73,33 @@ Add the code from below to `test_helper.rb`:
78
73
  class ActiveSupport::TestCase
79
74
  # Already existing code
80
75
  SmashingDocs.config do |c|
81
- c.template_file = 'test/template.md.erb'
82
- c.output_file = 'api_docs.md'
76
+ c.template_file = 'smashing_docs/template.md'
77
+ c.output_file = 'smashing_docs/api_docs.md'
78
+ c.run_all = true
83
79
  end
84
80
  # More code
85
81
  end
86
82
 
87
- MiniTest::Unit.after_tests { SmashingDocs.finish! }
88
- ```
89
- #### To run on all controller tests
90
- Add this to `test_helper.rb` as well:
91
- ```ruby
92
83
  class ActionController::TestCase < ActiveSupport::TestCase
93
84
  def teardown
94
- SmashingDocs.run!(request, response)
85
+ SmashingDocs.run!(request, response, true)
95
86
  end
96
87
  end
88
+
89
+ MiniTest::Unit.after_tests { SmashingDocs.finish! }
97
90
  ```
98
91
 
99
- Your code should look like this:
92
+ #### To run on only select tests
93
+ Set the `c.run_all` line to `false` in `test_helper.rb`
100
94
  ```ruby
101
- class ActiveSupport::TestCase
102
- # Already existing code
103
- SmashingDocs.config do |c|
104
- c.template_file = 'test/template.md.erb'
105
- c.output_file = 'api_docs.md'
106
- end
107
- # More code
108
- end
109
-
110
- class ActionController::TestCase < ActiveSupport::TestCase
111
- def teardown
112
- SmashingDocs.run!(request, response)
113
- end
95
+ SmashingDocs.config do |c|
96
+ c.template_file = 'smashing_docs/template.md'
97
+ c.output_file = 'smashing_docs/api_docs.md'
98
+ c.run_all = false
114
99
  end
115
-
116
- MiniTest::Unit.after_tests { SmashingDocs.finish! }
117
100
  ```
118
101
 
119
-
120
- #### To run on only select tests
121
- Just add `SmashingDocs.run!(request, response)` to specific tests
102
+ Then just add `SmashingDocs.run!(request, response)` to specific tests
122
103
  ```ruby
123
104
  def get_index
124
105
  get :index
@@ -129,8 +110,9 @@ end
129
110
 
130
111
  ## Setting a template
131
112
 
132
- If you copied the code from above, SmashingDocs will look for a template file located at either
133
- `test/template.md.erb` or `spec/template.md.erb`, depending on your test suite.
113
+ If you copied the code from above, SmashingDocs will look for a template file located in
114
+ `smashing_docs/template.md`
115
+
134
116
  This template may be customized to fit your needs.
135
117
 
136
118
  ```erb
@@ -139,7 +121,6 @@ This template may be customized to fit your needs.
139
121
  <%= request.params %>
140
122
  <%= response.body %>
141
123
  <%= information[:note] %>
142
- <%= aside %>
143
124
  ```
144
125
 
145
126
  ## Where to find the docs
@@ -8,22 +8,41 @@ RSpec.describe SmashingDocs do
8
8
  let(:tests) { SmashingDocs.current.tests }
9
9
 
10
10
  describe ".run!(request, response)" do
11
- context "when no tests have been run" do
12
- it "has done nothing" do
13
- expect(tests.length).to eq(0)
11
+ context "when run_all config is set to true" do
12
+ context "when no tests have been run" do
13
+ it "has done nothing" do
14
+ expect(tests.length).to eq(0)
15
+ end
14
16
  end
15
- end
16
- context "running 1 test" do
17
- it "adds the test to the list of tests" do
18
- SmashingDocs.run!(request, response)
19
- expect(tests.length).to eq(1)
20
- expect(tests.first).to be_a(SmashingDocs::TestCase)
17
+ context "running 1 test" do
18
+ it "adds the test to the list of tests" do
19
+ SmashingDocs.run!(request, response)
20
+ expect(tests.length).to eq(1)
21
+ expect(tests.first).to be_a(SmashingDocs::TestCase)
22
+ end
23
+ end
24
+ context "running 2 tests" do
25
+ it "adds both tests to the list of tests" do
26
+ 2.times { SmashingDocs.run!(request, response) }
27
+ expect(tests.length).to eq(2)
28
+ end
21
29
  end
22
30
  end
23
- context "running 2 tests" do
24
- it "adds both tests to the list of tests" do
25
- 2.times { SmashingDocs.run!(request, response) }
26
- expect(tests.length).to eq(2)
31
+
32
+ context "when run_all config is set to false" do
33
+ context "tests triggered by RSpec after hook" do
34
+ it "does not add the tests" do
35
+ SmashingDocs::Conf.run_all = false
36
+ SmashingDocs.run!(request, response, true)
37
+ expect(tests.length).to eq(0)
38
+ end
39
+ end
40
+ context "tests added by the user" do
41
+ it "adds the tests" do
42
+ SmashingDocs::Conf.run_all = false
43
+ SmashingDocs.run!(request, response)
44
+ expect(tests.length).to eq(1)
45
+ end
27
46
  end
28
47
  end
29
48
  end
@@ -48,6 +67,21 @@ RSpec.describe SmashingDocs do
48
67
  expect(File.read(file)).to include("You can use ERB")
49
68
  end
50
69
  end
70
+ context "when there are no tests" do
71
+ it "does not overwrite the docs with an empty file" do
72
+ # Generate docs
73
+ SmashingDocs.run!(first, response)
74
+ SmashingDocs.run!(last, response)
75
+ SmashingDocs.finish!
76
+ expect(File).to exist(file)
77
+ expect(File.read(file)).to include("You can use ERB")
78
+
79
+ SmashingDocs.current.tests = []
80
+ SmashingDocs.finish!
81
+ expect(File).to exist(file)
82
+ expect(File.read(file)).to include("You can use ERB")
83
+ end
84
+ end
51
85
  end
52
86
 
53
87
  describe ".skip" do
@@ -81,14 +115,4 @@ RSpec.describe SmashingDocs do
81
115
  expect(tests.first.compile_template).to include("Endpoint note")
82
116
  end
83
117
  end
84
-
85
- describe ".aside(message)" do
86
- # The template file must have <%= information[:note] %>
87
- it "sends information to be displayed about the endpoint" do
88
- SmashingDocs.aside("I am an aside")
89
- SmashingDocs.run!(first, response)
90
- expect(tests.first.compile_template).to include("<aside class='notice'>")
91
- expect(tests.first.compile_template).to include("I am an aside")
92
- end
93
- end
94
118
  end
@@ -5,6 +5,7 @@ RSpec.describe SmashingDocs::Conf do
5
5
  SmashingDocs.config do |c|
6
6
  c.template_file = "gem_spec/fake_template.md.erb"
7
7
  c.output_file = "api_docs.md"
8
+ c.run_all = true
8
9
  end
9
10
  }
10
11
  it "sets the output file" do
@@ -14,4 +15,8 @@ RSpec.describe SmashingDocs::Conf do
14
15
  it "sets the template file" do
15
16
  expect(SmashingDocs::Conf.template_file).to eq("gem_spec/fake_template.md.erb")
16
17
  end
18
+
19
+ it "sets run_all" do
20
+ expect(SmashingDocs::Conf.run_all).to eq(true)
21
+ end
17
22
  end
@@ -0,0 +1,6 @@
1
+ You can use ERB to format each test case.
2
+ GET
3
+ api/aaa
4
+ {:id=>12}
5
+ {"id": 12, "name": "rick"}
6
+ Endpoint note
@@ -4,4 +4,3 @@ You can use ERB to format each test case.
4
4
  <%= request.params %>
5
5
  <%= response.body %>
6
6
  <%= information[:note] %>
7
- <%= aside %>
@@ -13,7 +13,7 @@ RSpec.describe SmashingDocs::TestCase do
13
13
  end
14
14
 
15
15
  context "with a template file" do
16
- let!(:template) { SmashingDocs.config { |c| c.template_file = 'spec/fake_template.md.erb' } }
16
+ let!(:template) { SmashingDocs.config { |c| c.template_file = 'gem_rspec/fake_template.md.erb' } }
17
17
  it "sets the template file and returns docs matching the template" do
18
18
  test_case.template = SmashingDocs::Conf.template
19
19
  expect(test_case.compile_template).to include("use ERB")
data/lib/base.rb CHANGED
@@ -16,28 +16,27 @@ class SmashingDocs
16
16
  @tests = []
17
17
  end
18
18
 
19
- def aside(msg)
20
- @aside = ''
21
- @aside = "<aside class='notice'>\n #{msg}\n</aside>"
22
- end
23
-
24
19
  def information(key, value)
25
20
  @information[key] = value
26
21
  end
27
22
 
28
- def run!(request, response)
23
+ def run!(request, response, called_by_test_hook)
24
+ run_all = self.class::Conf.run_all
29
25
  if @skip
30
26
  @skip = false
31
27
  return
32
28
  end
33
- add_test_case(request, response)
29
+ if run_all
30
+ add_test_case(request, response)
31
+ else
32
+ add_test_case(request, response) unless called_by_test_hook
33
+ end
34
34
  @information = {}
35
- @skip = false
36
35
  self
37
36
  end
38
37
 
39
38
  def add_test_case(request, response)
40
- test = self.class::TestCase.new(request, response, @information, @aside)
39
+ test = self.class::TestCase.new(request, response, @information)
41
40
  test.template = self.class::Conf.template
42
41
  self.tests << test
43
42
  end
@@ -67,13 +66,15 @@ class SmashingDocs
67
66
  # for an instance variable to be declared and used
68
67
 
69
68
  def self.finish!
70
- current.sort_by_url!
71
- current.output_testcases_to_file
72
- current.clean_up!
69
+ unless current.tests.empty?
70
+ current.sort_by_url!
71
+ current.output_testcases_to_file
72
+ current.clean_up!
73
+ end
73
74
  end
74
75
 
75
- def self.run!(request, response)
76
- current.run!(request, response)
76
+ def self.run!(request, response, called_by_test_hook = false)
77
+ current.run!(request, response, called_by_test_hook)
77
78
  end
78
79
 
79
80
  def self.skip
@@ -84,10 +85,6 @@ class SmashingDocs
84
85
  current.information(key, value)
85
86
  end
86
87
 
87
- def self.aside(message)
88
- current.aside(message)
89
- end
90
-
91
88
  def self.current
92
89
  # Behaves like an instance of SmashingDocs class
93
90
  Thread.current[:instance] ||= self.new
data/lib/conf.rb CHANGED
@@ -1,12 +1,14 @@
1
1
  class SmashingDocs::Conf
2
2
  class << self
3
- attr_accessor :template_file, :output_file
4
-
5
- @output_file = 'documentation.md'
3
+ attr_accessor :template_file, :output_file, :run_all
6
4
 
7
5
  def template
8
6
  raise 'You must set a template file.' unless template_file
9
- @template ||= File.read(template_file)
7
+ File.read(template_file)
8
+ end
9
+
10
+ def run_all_tests
11
+ run_all
10
12
  end
11
13
  end
12
14
  end
@@ -24,6 +24,7 @@ module SmashingDocumentation
24
24
  "SmashingDocs.config do |c|\n"\
25
25
  " c.template_file = 'smashing_docs/template.md'\n"\
26
26
  " c.output_file = 'smashing_docs/api_docs.md'\n"\
27
+ " c.run_all = true\n"\
27
28
  "end"
28
29
  ) unless File.readlines(destination).grep(/SmashingDocs.config/).any?
29
30
  end
@@ -34,7 +35,7 @@ module SmashingDocumentation
34
35
  insert_into_file(
35
36
  destination,
36
37
  "\n config.after(:each, type: :controller) do\n"\
37
- " SmashingDocs.run!(request, response)\n"\
38
+ " SmashingDocs.run!(request, response, true)\n"\
38
39
  " end\n"\
39
40
  " config.after(:suite) { SmashingDocs.finish! }",
40
41
  after: "RSpec.configure do |config|"
data/lib/test_case.rb CHANGED
@@ -1,11 +1,11 @@
1
1
  require 'erb'
2
2
 
3
3
  class SmashingDocs::TestCase
4
- attr_reader :request, :response, :created_at, :information, :aside
4
+ attr_reader :request, :response, :created_at, :information
5
5
  attr_accessor :template
6
6
 
7
- def initialize(request, response, information = {}, aside = '')
8
- @request, @response, @information, @aside = request, response, information, aside
7
+ def initialize(request, response, information = {})
8
+ @request, @response, @information = request, response, information
9
9
  @created_at = Time.now
10
10
  end
11
11
 
@@ -10,7 +10,7 @@ Gem::Specification.new do |s|
10
10
  s.require_paths = ['lib']
11
11
  s.summary = "Uses your test cases to write example documentation for your API."
12
12
  s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
13
- s.version = '0.1.0'
13
+ s.version = '1.0.0'
14
14
 
15
15
  s.add_development_dependency "bundler", "~> 1.11"
16
16
  s.add_development_dependency "rake", "~> 10.0"
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: smashing_docs
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.0
4
+ version: 1.0.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Tyler Rockwell
@@ -10,7 +10,7 @@ authors:
10
10
  autorequire:
11
11
  bindir: bin
12
12
  cert_chain: []
13
- date: 2016-02-23 00:00:00.000000000 Z
13
+ date: 2016-02-24 00:00:00.000000000 Z
14
14
  dependencies:
15
15
  - !ruby/object:Gem::Dependency
16
16
  name: bundler