smashing_docs 0.0.2 → 0.1.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/.rspec +1 -0
- data/Gemfile +4 -0
- data/Gemfile.lock +88 -0
- data/README.md +14 -4
- data/{spec → gem_rspec}/base_spec.rb +9 -7
- data/{spec → gem_rspec}/conf_spec.rb +4 -4
- data/{spec → gem_rspec}/fake_output.md +0 -0
- data/{spec → gem_rspec}/fake_template.md.erb +0 -0
- data/gem_rspec/install_generator_spec.rb +44 -0
- data/gem_rspec/spec_helper.rb +29 -0
- data/{spec → gem_rspec}/test_case_spec.rb +0 -0
- data/lib/generators/smashing_documentation/install_generator.rb +52 -0
- data/lib/templates/real_template.md +16 -0
- data/smashing_docs.gemspec +2 -1
- data/spec/spec_helper.rb +0 -27
- metadata +28 -13
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA1:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 51d3931b8339c80e86f365d38579ca206aaec9e6
|
4
|
+
data.tar.gz: ef9f7460e973252cf1d722423d5b201de50ec238
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: d9d6a0a33ee29cdbf5b22ba8b2fbd7235274cb36b4e81b96a4e6af76de8bf72d19f7acf474369c1de77ee2eb245d36ee626c910d785ee13ffb3d7e7d8722c18e
|
7
|
+
data.tar.gz: 2e8b0895112ea255a09a3cbebed9a747fbdd2a19e4ff7d7864dcb5d1aa9de4f238481119addd7c3c8b2a2a8801e7105ced9ed558f90e361e7d97ecece0dd8c5c
|
data/.rspec
CHANGED
data/Gemfile
ADDED
data/Gemfile.lock
ADDED
@@ -0,0 +1,88 @@
|
|
1
|
+
PATH
|
2
|
+
remote: .
|
3
|
+
specs:
|
4
|
+
smashing_docs (0.0.2)
|
5
|
+
|
6
|
+
GEM
|
7
|
+
remote: https://rubygems.org/
|
8
|
+
specs:
|
9
|
+
actionpack (4.2.5.1)
|
10
|
+
actionview (= 4.2.5.1)
|
11
|
+
activesupport (= 4.2.5.1)
|
12
|
+
rack (~> 1.6)
|
13
|
+
rack-test (~> 0.6.2)
|
14
|
+
rails-dom-testing (~> 1.0, >= 1.0.5)
|
15
|
+
rails-html-sanitizer (~> 1.0, >= 1.0.2)
|
16
|
+
actionview (4.2.5.1)
|
17
|
+
activesupport (= 4.2.5.1)
|
18
|
+
builder (~> 3.1)
|
19
|
+
erubis (~> 2.7.0)
|
20
|
+
rails-dom-testing (~> 1.0, >= 1.0.5)
|
21
|
+
rails-html-sanitizer (~> 1.0, >= 1.0.2)
|
22
|
+
activesupport (4.2.5.1)
|
23
|
+
i18n (~> 0.7)
|
24
|
+
json (~> 1.7, >= 1.7.7)
|
25
|
+
minitest (~> 5.1)
|
26
|
+
thread_safe (~> 0.3, >= 0.3.4)
|
27
|
+
tzinfo (~> 1.1)
|
28
|
+
builder (3.2.2)
|
29
|
+
diff-lcs (1.2.5)
|
30
|
+
erubis (2.7.0)
|
31
|
+
generator_spec (0.9.3)
|
32
|
+
activesupport (>= 3.0.0)
|
33
|
+
railties (>= 3.0.0)
|
34
|
+
i18n (0.7.0)
|
35
|
+
json (1.8.3)
|
36
|
+
loofah (2.0.3)
|
37
|
+
nokogiri (>= 1.5.9)
|
38
|
+
mini_portile2 (2.0.0)
|
39
|
+
minitest (5.8.4)
|
40
|
+
nokogiri (1.6.7.2)
|
41
|
+
mini_portile2 (~> 2.0.0.rc2)
|
42
|
+
rack (1.6.4)
|
43
|
+
rack-test (0.6.3)
|
44
|
+
rack (>= 1.0)
|
45
|
+
rails-deprecated_sanitizer (1.0.3)
|
46
|
+
activesupport (>= 4.2.0.alpha)
|
47
|
+
rails-dom-testing (1.0.7)
|
48
|
+
activesupport (>= 4.2.0.beta, < 5.0)
|
49
|
+
nokogiri (~> 1.6.0)
|
50
|
+
rails-deprecated_sanitizer (>= 1.0.1)
|
51
|
+
rails-html-sanitizer (1.0.3)
|
52
|
+
loofah (~> 2.0)
|
53
|
+
railties (4.2.5.1)
|
54
|
+
actionpack (= 4.2.5.1)
|
55
|
+
activesupport (= 4.2.5.1)
|
56
|
+
rake (>= 0.8.7)
|
57
|
+
thor (>= 0.18.1, < 2.0)
|
58
|
+
rake (10.5.0)
|
59
|
+
rspec (3.4.0)
|
60
|
+
rspec-core (~> 3.4.0)
|
61
|
+
rspec-expectations (~> 3.4.0)
|
62
|
+
rspec-mocks (~> 3.4.0)
|
63
|
+
rspec-core (3.4.2)
|
64
|
+
rspec-support (~> 3.4.0)
|
65
|
+
rspec-expectations (3.4.0)
|
66
|
+
diff-lcs (>= 1.2.0, < 2.0)
|
67
|
+
rspec-support (~> 3.4.0)
|
68
|
+
rspec-mocks (3.4.1)
|
69
|
+
diff-lcs (>= 1.2.0, < 2.0)
|
70
|
+
rspec-support (~> 3.4.0)
|
71
|
+
rspec-support (3.4.1)
|
72
|
+
thor (0.19.1)
|
73
|
+
thread_safe (0.3.5)
|
74
|
+
tzinfo (1.2.2)
|
75
|
+
thread_safe (~> 0.1)
|
76
|
+
|
77
|
+
PLATFORMS
|
78
|
+
ruby
|
79
|
+
|
80
|
+
DEPENDENCIES
|
81
|
+
bundler (~> 1.11)
|
82
|
+
generator_spec
|
83
|
+
rake (~> 10.0)
|
84
|
+
rspec (~> 3.0)
|
85
|
+
smashing_docs!
|
86
|
+
|
87
|
+
BUNDLED WITH
|
88
|
+
1.11.2
|
data/README.md
CHANGED
@@ -6,16 +6,26 @@
|
|
6
6
|
|
7
7
|
In your gemfile add the following to your test group:
|
8
8
|
|
9
|
-
`gem 'smashing_docs',
|
9
|
+
`gem 'smashing_docs', '~> 0.0.3'`
|
10
10
|
|
11
11
|
Installation differs for RSpec/Minitest, so scroll to the appropriate section for guidance.
|
12
12
|
|
13
|
-
##
|
13
|
+
## Automatic Installation (RSpec only!)
|
14
|
+
|
15
|
+
After you bundle, run:
|
16
|
+
|
17
|
+
`rails generate smashing_documentation:install`
|
18
|
+
|
19
|
+
SmashingDocs will be configured to run on all your controller tests with the default
|
20
|
+
template, whenever you run your tests. Your API documentation will appear in the smashing_docs
|
21
|
+
folder in the root of your Rails app.
|
22
|
+
|
23
|
+
## Manual RSpec Installation
|
14
24
|
|
15
25
|
Add this to your `rails_helper.rb` It should go outside of other blocks
|
16
26
|
(Do not place it inside the `RSpec.configure` block).
|
17
27
|
```ruby
|
18
|
-
|
28
|
+
SmashingDocs.config do |c|
|
19
29
|
c.template_file = 'spec/template.md.erb'
|
20
30
|
c.output_file = 'api_docs.md'
|
21
31
|
end
|
@@ -61,7 +71,7 @@ it "responds with 200" do
|
|
61
71
|
end
|
62
72
|
```
|
63
73
|
|
64
|
-
## Minitest Installation
|
74
|
+
## Manual Minitest Installation
|
65
75
|
|
66
76
|
Add the code from below to `test_helper.rb`:
|
67
77
|
```ruby
|
@@ -39,12 +39,14 @@ RSpec.describe SmashingDocs do
|
|
39
39
|
end
|
40
40
|
|
41
41
|
describe ".finish!" do
|
42
|
-
|
43
|
-
|
44
|
-
|
45
|
-
|
46
|
-
|
47
|
-
|
42
|
+
context "when there are tests" do
|
43
|
+
it "creates the docs file with output from the template" do
|
44
|
+
SmashingDocs.run!(first, response)
|
45
|
+
SmashingDocs.run!(last, response)
|
46
|
+
SmashingDocs.finish!
|
47
|
+
expect(File).to exist(file)
|
48
|
+
expect(File.read(file)).to include("You can use ERB")
|
49
|
+
end
|
48
50
|
end
|
49
51
|
end
|
50
52
|
|
@@ -86,7 +88,7 @@ RSpec.describe SmashingDocs do
|
|
86
88
|
SmashingDocs.aside("I am an aside")
|
87
89
|
SmashingDocs.run!(first, response)
|
88
90
|
expect(tests.first.compile_template).to include("<aside class='notice'>")
|
89
|
-
expect(tests.first.compile_template).to include("I am an aside")
|
91
|
+
expect(tests.first.compile_template).to include("I am an aside")
|
90
92
|
end
|
91
93
|
end
|
92
94
|
end
|
@@ -3,15 +3,15 @@ require 'spec_helper'
|
|
3
3
|
RSpec.describe SmashingDocs::Conf do
|
4
4
|
let!(:config) {
|
5
5
|
SmashingDocs.config do |c|
|
6
|
-
c.template_file = "
|
6
|
+
c.template_file = "gem_spec/fake_template.md.erb"
|
7
7
|
c.output_file = "api_docs.md"
|
8
8
|
end
|
9
9
|
}
|
10
|
-
it "sets the
|
10
|
+
it "sets the output file" do
|
11
11
|
expect(SmashingDocs::Conf.output_file).to eq("api_docs.md")
|
12
12
|
end
|
13
13
|
|
14
|
-
it "sets the
|
15
|
-
expect(SmashingDocs::Conf.template_file).to eq("
|
14
|
+
it "sets the template file" do
|
15
|
+
expect(SmashingDocs::Conf.template_file).to eq("gem_spec/fake_template.md.erb")
|
16
16
|
end
|
17
17
|
end
|
File without changes
|
File without changes
|
@@ -0,0 +1,44 @@
|
|
1
|
+
require 'spec_helper'
|
2
|
+
require 'generator_spec'
|
3
|
+
require 'generators/smashing_documentation/install_generator'
|
4
|
+
RSpec.describe SmashingDocumentation::Generators::InstallGenerator, type: :generator do
|
5
|
+
let(:rails_helper) { "spec/rails_helper.rb" }
|
6
|
+
let(:spec_helper) { "spec/spec_helper.rb" }
|
7
|
+
let(:docs_template) { "smashing_docs/template.md" }
|
8
|
+
context "when rspec is installed" do
|
9
|
+
describe "#update_spec_helper" do
|
10
|
+
it "appends the SmashingDocs config to rails_helper.rb" do
|
11
|
+
run_generator
|
12
|
+
expect(File).to exist(rails_helper)
|
13
|
+
expect(File.read(rails_helper)).to include("SmashingDocs.config do")
|
14
|
+
end
|
15
|
+
|
16
|
+
it "appends test suite hooks inside RSpec.configure block in spec_helper.rb" do
|
17
|
+
run_generator
|
18
|
+
expect(File).to exist(spec_helper)
|
19
|
+
expect(File.read(spec_helper)).to include("config.after(:each,")
|
20
|
+
expect(File.read(spec_helper)).to include("config.after(:suite)")
|
21
|
+
end
|
22
|
+
end
|
23
|
+
|
24
|
+
describe "#generate_docs_template" do
|
25
|
+
it "generates the default docs template" do
|
26
|
+
run_generator
|
27
|
+
expect(File).to exist(docs_template)
|
28
|
+
expect(File.read(docs_template)).to include("request.method")
|
29
|
+
expect(File.read(docs_template)).to include("response.body")
|
30
|
+
end
|
31
|
+
end
|
32
|
+
end
|
33
|
+
|
34
|
+
context "when rspec is not installed" do
|
35
|
+
it "does not install smashing_docs" do
|
36
|
+
File.rename('spec', 's') if Dir.exists?('spec')
|
37
|
+
run_generator
|
38
|
+
expect(File).to_not exist(rails_helper)
|
39
|
+
File.rename('s', 'spec') if Dir.exists?('s')
|
40
|
+
|
41
|
+
# STDOUT is not tested here because it is suppressed in generator tests
|
42
|
+
end
|
43
|
+
end
|
44
|
+
end
|
@@ -0,0 +1,29 @@
|
|
1
|
+
$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
|
2
|
+
require 'smashing_docs'
|
3
|
+
|
4
|
+
RSpec.configure do |config|
|
5
|
+
config.expect_with :rspec do |expectations|
|
6
|
+
expectations.include_chain_clauses_in_custom_matcher_descriptions = true
|
7
|
+
end
|
8
|
+
config.before(:each) do
|
9
|
+
SmashingDocs.config do |c|
|
10
|
+
c.template_file = 'gem_rspec/fake_template.md.erb'
|
11
|
+
c.output_file = 'gem_rspec/fake_output.md'
|
12
|
+
end
|
13
|
+
end
|
14
|
+
config.after(:each) do
|
15
|
+
SmashingDocs.finish!
|
16
|
+
end
|
17
|
+
end
|
18
|
+
|
19
|
+
# Include some fake structs that act like response/request objects.
|
20
|
+
Request = Struct.new :method, :params, :path
|
21
|
+
Response = Struct.new :body, :success?
|
22
|
+
|
23
|
+
def request
|
24
|
+
Request.new("GET", {id: 12}, 'api/users')
|
25
|
+
end
|
26
|
+
|
27
|
+
def response
|
28
|
+
Response.new('{"id": 12, "name": "rick"}', true)
|
29
|
+
end
|
File without changes
|
@@ -0,0 +1,52 @@
|
|
1
|
+
require 'rails/generators'
|
2
|
+
module SmashingDocumentation
|
3
|
+
module Generators
|
4
|
+
class InstallGenerator < Rails::Generators::Base
|
5
|
+
source_root File.expand_path("../../../templates/", __FILE__)
|
6
|
+
|
7
|
+
def install
|
8
|
+
if Dir.exists?('spec')
|
9
|
+
update_rails_helper
|
10
|
+
update_spec_helper
|
11
|
+
generate_docs_template
|
12
|
+
else
|
13
|
+
puts "It does not appear that you have RSpec installed in your app"
|
14
|
+
puts "Please set up RSpec before running this installer"
|
15
|
+
end
|
16
|
+
end
|
17
|
+
|
18
|
+
private
|
19
|
+
|
20
|
+
def update_rails_helper
|
21
|
+
destination = "spec/rails_helper.rb"
|
22
|
+
create_file(destination) unless File.exist?(destination)
|
23
|
+
append_file(destination,
|
24
|
+
"SmashingDocs.config do |c|\n"\
|
25
|
+
" c.template_file = 'smashing_docs/template.md'\n"\
|
26
|
+
" c.output_file = 'smashing_docs/api_docs.md'\n"\
|
27
|
+
"end"
|
28
|
+
) unless File.readlines(destination).grep(/SmashingDocs.config/).any?
|
29
|
+
end
|
30
|
+
|
31
|
+
def update_spec_helper
|
32
|
+
destination = "spec/spec_helper.rb"
|
33
|
+
if File.exist?(destination)
|
34
|
+
insert_into_file(
|
35
|
+
destination,
|
36
|
+
"\n config.after(:each, type: :controller) do\n"\
|
37
|
+
" SmashingDocs.run!(request, response)\n"\
|
38
|
+
" end\n"\
|
39
|
+
" config.after(:suite) { SmashingDocs.finish! }",
|
40
|
+
after: "RSpec.configure do |config|"
|
41
|
+
) unless File.readlines(destination).grep(/SmashingDocs.finish/).any?
|
42
|
+
end
|
43
|
+
end
|
44
|
+
|
45
|
+
def generate_docs_template
|
46
|
+
source = "real_template.md"
|
47
|
+
destination = "smashing_docs/template.md"
|
48
|
+
copy_file(source, destination) unless File.exist?(destination)
|
49
|
+
end
|
50
|
+
end
|
51
|
+
end
|
52
|
+
end
|
@@ -0,0 +1,16 @@
|
|
1
|
+
#### <%= request.method %> <%= request.path %>
|
2
|
+
|
3
|
+
<%= information[:note] %>
|
4
|
+
|
5
|
+
| Param | Value |
|
6
|
+
| ----- | ----- |
|
7
|
+
<%= table_entries = []
|
8
|
+
request.params.except(:controller, :action, :format).each do |param, value|
|
9
|
+
table_entries << "| #{param} | #{value} |"
|
10
|
+
end
|
11
|
+
table_entries.join("\n") %>
|
12
|
+
|
13
|
+
Response: <%= response.status %>
|
14
|
+
```json
|
15
|
+
<%= JSON.pretty_generate(JSON.parse(response.body)) %>
|
16
|
+
```
|
data/smashing_docs.gemspec
CHANGED
@@ -10,9 +10,10 @@ 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.0
|
13
|
+
s.version = '0.1.0'
|
14
14
|
|
15
15
|
s.add_development_dependency "bundler", "~> 1.11"
|
16
16
|
s.add_development_dependency "rake", "~> 10.0"
|
17
17
|
s.add_development_dependency "rspec", "~> 3.0"
|
18
|
+
s.add_development_dependency "generator_spec"
|
18
19
|
end
|
data/spec/spec_helper.rb
CHANGED
@@ -1,29 +1,2 @@
|
|
1
|
-
$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
|
2
|
-
require 'smashing_docs'
|
3
|
-
|
4
1
|
RSpec.configure do |config|
|
5
|
-
config.expect_with :rspec do |expectations|
|
6
|
-
expectations.include_chain_clauses_in_custom_matcher_descriptions = true
|
7
|
-
end
|
8
|
-
config.before(:each) do
|
9
|
-
SmashingDocs.config do |c|
|
10
|
-
c.template_file = 'spec/fake_template.md.erb'
|
11
|
-
c.output_file = 'spec/fake_output.md'
|
12
|
-
end
|
13
|
-
end
|
14
|
-
config.after(:each) do
|
15
|
-
SmashingDocs.finish!
|
16
|
-
end
|
17
|
-
end
|
18
|
-
|
19
|
-
# Include some fake structs that act like response/request objects.
|
20
|
-
Request = Struct.new :method, :params, :path
|
21
|
-
Response = Struct.new :body, :success?
|
22
|
-
|
23
|
-
def request
|
24
|
-
Request.new("GET", {id: 12}, 'api/users')
|
25
|
-
end
|
26
|
-
|
27
|
-
def response
|
28
|
-
Response.new('{"id": 12, "name": "rick"}', true)
|
29
2
|
end
|
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.0
|
4
|
+
version: 0.1.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-23 00:00:00.000000000 Z
|
14
14
|
dependencies:
|
15
15
|
- !ruby/object:Gem::Dependency
|
16
16
|
name: bundler
|
@@ -54,6 +54,20 @@ dependencies:
|
|
54
54
|
- - "~>"
|
55
55
|
- !ruby/object:Gem::Version
|
56
56
|
version: '3.0'
|
57
|
+
- !ruby/object:Gem::Dependency
|
58
|
+
name: generator_spec
|
59
|
+
requirement: !ruby/object:Gem::Requirement
|
60
|
+
requirements:
|
61
|
+
- - ">="
|
62
|
+
- !ruby/object:Gem::Version
|
63
|
+
version: '0'
|
64
|
+
type: :development
|
65
|
+
prerelease: false
|
66
|
+
version_requirements: !ruby/object:Gem::Requirement
|
67
|
+
requirements:
|
68
|
+
- - ">="
|
69
|
+
- !ruby/object:Gem::Version
|
70
|
+
version: '0'
|
57
71
|
description: Write API documentation using existing controller tests.
|
58
72
|
email:
|
59
73
|
executables: []
|
@@ -62,21 +76,27 @@ extra_rdoc_files: []
|
|
62
76
|
files:
|
63
77
|
- ".gitignore"
|
64
78
|
- ".rspec"
|
79
|
+
- Gemfile
|
80
|
+
- Gemfile.lock
|
65
81
|
- README.md
|
66
82
|
- Rakefile
|
67
83
|
- api_docs.md
|
68
84
|
- documentation.md
|
85
|
+
- gem_rspec/base_spec.rb
|
86
|
+
- gem_rspec/conf_spec.rb
|
87
|
+
- gem_rspec/fake_output.md
|
88
|
+
- gem_rspec/fake_template.md.erb
|
89
|
+
- gem_rspec/install_generator_spec.rb
|
90
|
+
- gem_rspec/spec_helper.rb
|
91
|
+
- gem_rspec/test_case_spec.rb
|
69
92
|
- lib/base.rb
|
70
93
|
- lib/conf.rb
|
94
|
+
- lib/generators/smashing_documentation/install_generator.rb
|
71
95
|
- lib/smashing_docs.rb
|
96
|
+
- lib/templates/real_template.md
|
72
97
|
- lib/test_case.rb
|
73
98
|
- smashing_docs.gemspec
|
74
|
-
- spec/base_spec.rb
|
75
|
-
- spec/conf_spec.rb
|
76
|
-
- spec/fake_output.md
|
77
|
-
- spec/fake_template.md.erb
|
78
99
|
- spec/spec_helper.rb
|
79
|
-
- spec/test_case_spec.rb
|
80
100
|
homepage: https://github.com/smashingboxes/smashing_docs
|
81
101
|
licenses:
|
82
102
|
- MIT
|
@@ -97,14 +117,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
|
|
97
117
|
version: '0'
|
98
118
|
requirements: []
|
99
119
|
rubyforge_project:
|
100
|
-
rubygems_version: 2.
|
120
|
+
rubygems_version: 2.5.1
|
101
121
|
signing_key:
|
102
122
|
specification_version: 4
|
103
123
|
summary: Uses your test cases to write example documentation for your API.
|
104
124
|
test_files:
|
105
|
-
- spec/base_spec.rb
|
106
|
-
- spec/conf_spec.rb
|
107
|
-
- spec/fake_output.md
|
108
|
-
- spec/fake_template.md.erb
|
109
125
|
- spec/spec_helper.rb
|
110
|
-
- spec/test_case_spec.rb
|