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 +4 -4
- data/README.md +30 -49
- data/gem_rspec/base_spec.rb +47 -23
- data/gem_rspec/conf_spec.rb +5 -0
- data/gem_rspec/fake_output.md +6 -0
- data/gem_rspec/fake_template.md.erb +0 -1
- data/gem_rspec/test_case_spec.rb +1 -1
- data/lib/base.rb +15 -18
- data/lib/conf.rb +6 -4
- data/lib/generators/smashing_documentation/install_generator.rb +2 -1
- data/lib/test_case.rb +3 -3
- data/smashing_docs.gemspec +1 -1
- metadata +2 -2
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA1:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 31bc78abe84edc9c4717b1b0d1c792c23cef3cdc
|
4
|
+
data.tar.gz: 8f1dce8a1fd1be5e34512a7ac4c2847142d6881e
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
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 = '
|
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
|
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
|
-
|
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
|
50
|
-
|
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
|
-
|
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 = '
|
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
|
-
|
92
|
+
#### To run on only select tests
|
93
|
+
Set the `c.run_all` line to `false` in `test_helper.rb`
|
100
94
|
```ruby
|
101
|
-
|
102
|
-
|
103
|
-
|
104
|
-
|
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
|
133
|
-
`
|
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
|
data/gem_rspec/base_spec.rb
CHANGED
@@ -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
|
12
|
-
|
13
|
-
|
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
|
-
|
16
|
-
|
17
|
-
|
18
|
-
|
19
|
-
|
20
|
-
|
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
|
-
|
24
|
-
|
25
|
-
|
26
|
-
|
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
|
data/gem_rspec/conf_spec.rb
CHANGED
@@ -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
|
data/gem_rspec/fake_output.md
CHANGED
data/gem_rspec/test_case_spec.rb
CHANGED
@@ -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 = '
|
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
|
-
|
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
|
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.
|
71
|
-
|
72
|
-
|
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
|
-
|
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
|
4
|
+
attr_reader :request, :response, :created_at, :information
|
5
5
|
attr_accessor :template
|
6
6
|
|
7
|
-
def initialize(request, response, information = {}
|
8
|
-
@request, @response, @information
|
7
|
+
def initialize(request, response, information = {})
|
8
|
+
@request, @response, @information = request, response, information
|
9
9
|
@created_at = Time.now
|
10
10
|
end
|
11
11
|
|
data/smashing_docs.gemspec
CHANGED
@@ -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 = '
|
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:
|
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-
|
13
|
+
date: 2016-02-24 00:00:00.000000000 Z
|
14
14
|
dependencies:
|
15
15
|
- !ruby/object:Gem::Dependency
|
16
16
|
name: bundler
|