doc_yo_self 0.0.1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +7 -0
- data/.gitignore +1 -0
- data/README.md +66 -0
- data/Rakefile +8 -0
- data/api_docs.md +0 -0
- data/doc_yo_self.gemspec +15 -0
- data/documentation.md +80 -0
- data/lib/base.rb +83 -0
- data/lib/conf.rb +12 -0
- data/lib/doc_yo_self.rb +4 -0
- data/lib/test_case.rb +15 -0
- data/test/fake_output.md +0 -0
- data/test/fake_template.md +7 -0
- data/test/test_base.rb +69 -0
- data/test/test_config.rb +15 -0
- data/test/test_helper.rb +30 -0
- data/test/test_test_case.rb +28 -0
- metadata +65 -0
checksums.yaml
ADDED
@@ -0,0 +1,7 @@
|
|
1
|
+
---
|
2
|
+
SHA1:
|
3
|
+
metadata.gz: 1dca5880b129ed713c81bfecb1ea14cc0b9626d7
|
4
|
+
data.tar.gz: f4f71b07c337878360beaae7bd95704646e39356
|
5
|
+
SHA512:
|
6
|
+
metadata.gz: 0a0163819d7f45e25692402dab3a108487ad1978eae2c8e4b9b8184b9b46e9c2d403af65c07d2394d6baa57d65a93f5f00f43ec885efa1fbf33c540534e3c68d
|
7
|
+
data.tar.gz: d8abe36cc4aec720b51bf12a1136ab9785dab713780c00b45324c7196d79851a09ceee84548b53263b2a8dd2766d996476bcb3f02d9bf84515abb3168ba76f1a
|
data/.gitignore
ADDED
@@ -0,0 +1 @@
|
|
1
|
+
/coverage/
|
data/README.md
ADDED
@@ -0,0 +1,66 @@
|
|
1
|
+
# Doc Yo Self
|
2
|
+
|
3
|
+
An auto documentation for Rails. Pop it into your test suite and watch it amaze.
|
4
|
+
|
5
|
+
Time for this project was provided by my employer, [SmashingBoxes](http://smashingboxes.com/). What a great place to work.
|
6
|
+
|
7
|
+
# Limitations
|
8
|
+
|
9
|
+
* **Current focus is MiniTest**. Probably will work with Rspec too, but that's not our focus right now.
|
10
|
+
* **Probably not thread safe**. Thread safety isn't a focus for this project right now. Pull requests welcome :-).
|
11
|
+
|
12
|
+
|
13
|
+
## Setup
|
14
|
+
|
15
|
+
```ruby
|
16
|
+
DocYoSelf.config do |c|
|
17
|
+
c.template_file = 'test/template.md.erb'
|
18
|
+
c.output = 'api_docs.md'
|
19
|
+
end
|
20
|
+
```
|
21
|
+
|
22
|
+
To run doc generation after every controller spec, put this into your `teardown` method. Or whatever method your test framework of choice will run after *every test*.
|
23
|
+
|
24
|
+
```ruby
|
25
|
+
def teardown
|
26
|
+
DocYoSelf.run!
|
27
|
+
end
|
28
|
+
```
|
29
|
+
|
30
|
+
Then put this at the bottom of your `test_helper.rb`:
|
31
|
+
|
32
|
+
```ruby
|
33
|
+
DocYoSelf.finish!
|
34
|
+
```
|
35
|
+
|
36
|
+
Or put it individually into only certain tests...
|
37
|
+
|
38
|
+
```ruby
|
39
|
+
def test_some_api
|
40
|
+
get :index, :users
|
41
|
+
assert response.status == 200
|
42
|
+
DocYoSelf.run!
|
43
|
+
end
|
44
|
+
```
|
45
|
+
|
46
|
+
## Usage
|
47
|
+
|
48
|
+
It will log all requests and responses by default, but you can add some **optional** parameters as well.
|
49
|
+
|
50
|
+
### Skipping documentation
|
51
|
+
|
52
|
+
```ruby
|
53
|
+
def test_stuff
|
54
|
+
DocYoSelf.skip
|
55
|
+
# Blahhh
|
56
|
+
end
|
57
|
+
```
|
58
|
+
|
59
|
+
## Adding notes
|
60
|
+
|
61
|
+
```ruby
|
62
|
+
def test_stuff
|
63
|
+
DocYoSelf.note "안녕하세요. This is a note."
|
64
|
+
# Blahhh
|
65
|
+
end
|
66
|
+
```
|
data/Rakefile
ADDED
data/api_docs.md
ADDED
File without changes
|
data/doc_yo_self.gemspec
ADDED
@@ -0,0 +1,15 @@
|
|
1
|
+
$:.push File.expand_path('../lib', __FILE__)
|
2
|
+
|
3
|
+
Gem::Specification.new do |s|
|
4
|
+
s.authors = ['Rick Carlino']
|
5
|
+
s.description = "An automatic API documentation generator."
|
6
|
+
s.email = 'rick.carlino@gmail.com'
|
7
|
+
s.files = `git ls-files`.split("\n")
|
8
|
+
s.homepage = 'https://github.com/rickcarlino/doc_yo_self'
|
9
|
+
s.license = 'MIT'
|
10
|
+
s.name = 'doc_yo_self'
|
11
|
+
s.require_paths = ['lib']
|
12
|
+
s.summary = "Uses your test cases to write example documentation for your API."
|
13
|
+
s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
|
14
|
+
s.version = '0.0.1'
|
15
|
+
end
|
data/documentation.md
ADDED
@@ -0,0 +1,80 @@
|
|
1
|
+
You can use ERB to format each test case.
|
2
|
+
GET
|
3
|
+
api/aaa
|
4
|
+
{:id=>12}
|
5
|
+
{"id": 12, "name": "rick"}
|
6
|
+
You can use ERB to format each test case.
|
7
|
+
GET
|
8
|
+
api/users
|
9
|
+
{:id=>12}
|
10
|
+
{"id": 12, "name": "rick"}
|
11
|
+
You can use ERB to format each test case.
|
12
|
+
GET
|
13
|
+
api/users
|
14
|
+
{:id=>12}
|
15
|
+
{"id": 12, "name": "rick"}
|
16
|
+
You can use ERB to format each test case.
|
17
|
+
GET
|
18
|
+
api/zzz
|
19
|
+
{:id=>12}
|
20
|
+
{"id": 12, "name": "rick"}
|
21
|
+
You can use ERB to format each test case.
|
22
|
+
GET
|
23
|
+
api/aaa
|
24
|
+
{:id=>12}
|
25
|
+
{"id": 12, "name": "rick"}
|
26
|
+
You can use ERB to format each test case.
|
27
|
+
GET
|
28
|
+
api/users
|
29
|
+
{:id=>12}
|
30
|
+
{"id": 12, "name": "rick"}
|
31
|
+
You can use ERB to format each test case.
|
32
|
+
GET
|
33
|
+
api/users
|
34
|
+
{:id=>12}
|
35
|
+
{"id": 12, "name": "rick"}
|
36
|
+
You can use ERB to format each test case.
|
37
|
+
GET
|
38
|
+
api/zzz
|
39
|
+
{:id=>12}
|
40
|
+
{"id": 12, "name": "rick"}
|
41
|
+
You can use ERB to format each test case.
|
42
|
+
GET
|
43
|
+
api/aaa
|
44
|
+
{:id=>12}
|
45
|
+
{"id": 12, "name": "rick"}
|
46
|
+
You can use ERB to format each test case.
|
47
|
+
GET
|
48
|
+
api/zzz
|
49
|
+
{:id=>12}
|
50
|
+
{"id": 12, "name": "rick"}
|
51
|
+
You can use ERB to format each test case.
|
52
|
+
GET
|
53
|
+
api/users
|
54
|
+
{:id=>12}
|
55
|
+
{"id": 12, "name": "rick"}
|
56
|
+
You can use ERB to format each test case.
|
57
|
+
GET
|
58
|
+
api/users
|
59
|
+
{:id=>12}
|
60
|
+
{"id": 12, "name": "rick"}
|
61
|
+
You can use ERB to format each test case.
|
62
|
+
GET
|
63
|
+
api/aaa
|
64
|
+
{:id=>12}
|
65
|
+
{"id": 12, "name": "rick"}
|
66
|
+
You can use ERB to format each test case.
|
67
|
+
GET
|
68
|
+
api/zzz
|
69
|
+
{:id=>12}
|
70
|
+
{"id": 12, "name": "rick"}
|
71
|
+
You can use ERB to format each test case.
|
72
|
+
GET
|
73
|
+
api/aaa
|
74
|
+
{:id=>12}
|
75
|
+
{"id": 12, "name": "rick"}
|
76
|
+
You can use ERB to format each test case.
|
77
|
+
GET
|
78
|
+
api/zzz
|
79
|
+
{:id=>12}
|
80
|
+
{"id": 12, "name": "rick"}
|
data/lib/base.rb
ADDED
@@ -0,0 +1,83 @@
|
|
1
|
+
class DocYoSelf
|
2
|
+
attr_accessor :tests
|
3
|
+
def initialize
|
4
|
+
@tests = []
|
5
|
+
@skip = 0 # <= Hate this.
|
6
|
+
end
|
7
|
+
|
8
|
+
def sort_by_url!
|
9
|
+
@tests.sort! do |x, y|
|
10
|
+
x.request.path <=> y.request.path
|
11
|
+
end
|
12
|
+
end
|
13
|
+
|
14
|
+
def clean_up!
|
15
|
+
@tests = []
|
16
|
+
end
|
17
|
+
|
18
|
+
def note(msg)
|
19
|
+
@note = msg || ''
|
20
|
+
end
|
21
|
+
|
22
|
+
def run!(request, response)
|
23
|
+
@skip += 1
|
24
|
+
return if @skip == 2 # Gross.
|
25
|
+
add_test_case(request, response, @note)
|
26
|
+
@note = ''
|
27
|
+
@skip = 0
|
28
|
+
self
|
29
|
+
end
|
30
|
+
|
31
|
+
def add_test_case(request, response, note)
|
32
|
+
test = self.class::TestCase.new(request, response, note)
|
33
|
+
test.template = self.class::Conf.template
|
34
|
+
self.tests << test
|
35
|
+
end
|
36
|
+
|
37
|
+
def skip
|
38
|
+
@skip += 1
|
39
|
+
end
|
40
|
+
|
41
|
+
def output_testcases_to_file
|
42
|
+
docs = self.class::Conf.output_file
|
43
|
+
raise 'No output file specific for DocYoSelf' unless docs
|
44
|
+
File.delete docs if File.exists? docs
|
45
|
+
write_to_file
|
46
|
+
end
|
47
|
+
|
48
|
+
def write_to_file
|
49
|
+
File.open(self.class::Conf.output_file, 'a') do |file|
|
50
|
+
@tests.each do |test|
|
51
|
+
file.write(test.compile_template)
|
52
|
+
end
|
53
|
+
end
|
54
|
+
end
|
55
|
+
|
56
|
+
# = = = =
|
57
|
+
|
58
|
+
def self.finish!
|
59
|
+
current.sort_by_url!
|
60
|
+
current.output_testcases_to_file
|
61
|
+
current.clean_up!
|
62
|
+
end
|
63
|
+
|
64
|
+
def self.run!(request, response)
|
65
|
+
current.run!(request, response)
|
66
|
+
end
|
67
|
+
|
68
|
+
def self.skip
|
69
|
+
current.skip
|
70
|
+
end
|
71
|
+
|
72
|
+
def self.note(msg)
|
73
|
+
current.note(msg)
|
74
|
+
end
|
75
|
+
|
76
|
+
def self.current
|
77
|
+
Thread.current[:dys_instance] ||= self.new
|
78
|
+
end
|
79
|
+
|
80
|
+
def self.config(&block)
|
81
|
+
yield(self::Conf)
|
82
|
+
end
|
83
|
+
end
|
data/lib/conf.rb
ADDED
@@ -0,0 +1,12 @@
|
|
1
|
+
class DocYoSelf::Conf
|
2
|
+
class << self
|
3
|
+
attr_accessor :template_file, :output_file
|
4
|
+
|
5
|
+
@output_file = 'documentation.md'
|
6
|
+
|
7
|
+
def template
|
8
|
+
raise 'You must set a template file.' unless template_file
|
9
|
+
@template ||= File.read(template_file)
|
10
|
+
end
|
11
|
+
end
|
12
|
+
end
|
data/lib/doc_yo_self.rb
ADDED
data/lib/test_case.rb
ADDED
@@ -0,0 +1,15 @@
|
|
1
|
+
require 'erb'
|
2
|
+
|
3
|
+
class DocYoSelf::TestCase
|
4
|
+
attr_reader :request, :response, :created_at, :note
|
5
|
+
attr_accessor :template
|
6
|
+
|
7
|
+
def initialize(request, response, note = '')
|
8
|
+
@request, @response, @note = request, response, note
|
9
|
+
@created_at = Time.now
|
10
|
+
end
|
11
|
+
|
12
|
+
def compile_template
|
13
|
+
ERB.new(template).result binding
|
14
|
+
end
|
15
|
+
end
|
data/test/fake_output.md
ADDED
File without changes
|
data/test/test_base.rb
ADDED
@@ -0,0 +1,69 @@
|
|
1
|
+
require_relative "test_helper"
|
2
|
+
|
3
|
+
class TestBase < DysTest
|
4
|
+
|
5
|
+
def test_run!
|
6
|
+
tests = DocYoSelf.current.tests
|
7
|
+
assert_equal 0, tests.length,
|
8
|
+
"Expected current tests to be an empty array"
|
9
|
+
DocYoSelf.run!(request, response)
|
10
|
+
assert_equal 1, tests.length,
|
11
|
+
"Expected run!() to increase number of tests"
|
12
|
+
assert tests.first.is_a?(DocYoSelf::TestCase)
|
13
|
+
DocYoSelf.run!(request, response)
|
14
|
+
assert_equal 2, tests.length,
|
15
|
+
"Expected run!() to increase number of tests"
|
16
|
+
assert_includes tests.first.compile_template,
|
17
|
+
"You can use ERB to format each test case",
|
18
|
+
"Did not load correct template file"
|
19
|
+
end
|
20
|
+
|
21
|
+
def test_sort!
|
22
|
+
first = Request.new("GET", {id: 12}, 'api/aaa')
|
23
|
+
last = Request.new("GET", {id: 12}, 'api/zzz')
|
24
|
+
DocYoSelf.run!(first, response)
|
25
|
+
DocYoSelf.run!(last, response)
|
26
|
+
results = DocYoSelf.current.sort_by_url!.map{|tc| tc.request.path}
|
27
|
+
assert_equal ["api/aaa", "api/zzz"], results,
|
28
|
+
"Did not sort test cases by request URL"
|
29
|
+
end
|
30
|
+
|
31
|
+
def test_finish!
|
32
|
+
file = DocYoSelf::Conf.output_file
|
33
|
+
first = Request.new("GET", {id: 12}, 'api/aaa')
|
34
|
+
last = Request.new("GET", {id: 12}, 'api/zzz')
|
35
|
+
DocYoSelf.run!(first, response)
|
36
|
+
DocYoSelf.run!(last, response)
|
37
|
+
DocYoSelf.finish!
|
38
|
+
assert File.exists?(file),
|
39
|
+
"Did not create an output file after finish!()ing"
|
40
|
+
assert_includes File.read(file), "You can use ERB",
|
41
|
+
"Did not utilize template to output docs."
|
42
|
+
end
|
43
|
+
|
44
|
+
def test_skip
|
45
|
+
file = DocYoSelf::Conf.output_file
|
46
|
+
tests= DocYoSelf.current.tests
|
47
|
+
first = Request.new("GET", {id: 12}, 'api/skip')
|
48
|
+
last = Request.new("GET", {id: 12}, 'api/noskip')
|
49
|
+
DocYoSelf.skip
|
50
|
+
DocYoSelf.run!(first, response)
|
51
|
+
DocYoSelf.run!(last, response)
|
52
|
+
assert_equal 1, tests.length,
|
53
|
+
"DYS Did not skip tests."
|
54
|
+
assert_equal 'api/noskip', tests.first.request.path,
|
55
|
+
"DYS Did not skip tests."
|
56
|
+
end
|
57
|
+
|
58
|
+
def test_note
|
59
|
+
file = DocYoSelf::Conf.output_file
|
60
|
+
tests= DocYoSelf.current.tests
|
61
|
+
first = Request.new("GET", {id: 12}, 'api/skip')
|
62
|
+
last = Request.new("GET", {id: 12}, 'api/noskip')
|
63
|
+
DocYoSelf.note "안녕하세요"
|
64
|
+
DocYoSelf.run!(first, response)
|
65
|
+
DocYoSelf.run!(last, response)
|
66
|
+
assert_includes tests.first.compile_template, "안녕하세요",
|
67
|
+
"Could not find note in documentation."
|
68
|
+
end
|
69
|
+
end
|
data/test/test_config.rb
ADDED
@@ -0,0 +1,15 @@
|
|
1
|
+
require_relative "test_helper"
|
2
|
+
|
3
|
+
class TestConfig < DysTest
|
4
|
+
|
5
|
+
def test_set_configs
|
6
|
+
DocYoSelf.config do |c|
|
7
|
+
c.template_file = 'test/template.md.erb'
|
8
|
+
c.output_file = 'api_docs.md'
|
9
|
+
end
|
10
|
+
assert_equal 'api_docs.md', DocYoSelf::Conf.output_file,
|
11
|
+
"Unable to set output file"
|
12
|
+
assert_equal 'test/template.md.erb', DocYoSelf::Conf.template_file,
|
13
|
+
"Unable to set template file"
|
14
|
+
end
|
15
|
+
end
|
data/test/test_helper.rb
ADDED
@@ -0,0 +1,30 @@
|
|
1
|
+
require "simplecov"
|
2
|
+
SimpleCov.start
|
3
|
+
require_relative '../lib/doc_yo_self'
|
4
|
+
require 'minitest/autorun'
|
5
|
+
require 'pry'
|
6
|
+
|
7
|
+
class DysTest < Minitest::Unit::TestCase
|
8
|
+
def setup
|
9
|
+
DocYoSelf.config do |c|
|
10
|
+
c.template_file = 'test/fake_template.md'
|
11
|
+
c.output_file = 'test/fake_output.md'
|
12
|
+
end
|
13
|
+
end
|
14
|
+
|
15
|
+
def teardown
|
16
|
+
DocYoSelf.finish!
|
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
|
30
|
+
end
|
@@ -0,0 +1,28 @@
|
|
1
|
+
require_relative "test_helper"
|
2
|
+
|
3
|
+
class TestTestCase < DysTest
|
4
|
+
|
5
|
+
def dys
|
6
|
+
@dys ||= DocYoSelf::TestCase.new(request, response)
|
7
|
+
end
|
8
|
+
|
9
|
+
def test_compile_template
|
10
|
+
template = "<%= 2 + 2 %>"
|
11
|
+
dys.template = template
|
12
|
+
assert_equal dys.template, template,
|
13
|
+
"Could not set a template."
|
14
|
+
assert_equal "4", dys.compile_template,
|
15
|
+
"Could not compile template"
|
16
|
+
end
|
17
|
+
|
18
|
+
def test_compile_with_file
|
19
|
+
DocYoSelf.config { |c| c.template_file = 'test/fake_template.md' }
|
20
|
+
test = DocYoSelf::TestCase.new(request, response)
|
21
|
+
test.template = DocYoSelf::Conf.template
|
22
|
+
assert_includes test.compile_template, "use ERB"
|
23
|
+
end
|
24
|
+
|
25
|
+
def test_created_at
|
26
|
+
assert dys.created_at.is_a?(Time)
|
27
|
+
end
|
28
|
+
end
|
metadata
ADDED
@@ -0,0 +1,65 @@
|
|
1
|
+
--- !ruby/object:Gem::Specification
|
2
|
+
name: doc_yo_self
|
3
|
+
version: !ruby/object:Gem::Version
|
4
|
+
version: 0.0.1
|
5
|
+
platform: ruby
|
6
|
+
authors:
|
7
|
+
- Rick Carlino
|
8
|
+
autorequire:
|
9
|
+
bindir: bin
|
10
|
+
cert_chain: []
|
11
|
+
date: 2014-08-29 00:00:00.000000000 Z
|
12
|
+
dependencies: []
|
13
|
+
description: An automatic API documentation generator.
|
14
|
+
email: rick.carlino@gmail.com
|
15
|
+
executables: []
|
16
|
+
extensions: []
|
17
|
+
extra_rdoc_files: []
|
18
|
+
files:
|
19
|
+
- .gitignore
|
20
|
+
- README.md
|
21
|
+
- Rakefile
|
22
|
+
- api_docs.md
|
23
|
+
- doc_yo_self.gemspec
|
24
|
+
- documentation.md
|
25
|
+
- lib/base.rb
|
26
|
+
- lib/conf.rb
|
27
|
+
- lib/doc_yo_self.rb
|
28
|
+
- lib/test_case.rb
|
29
|
+
- test/fake_output.md
|
30
|
+
- test/fake_template.md
|
31
|
+
- test/test_base.rb
|
32
|
+
- test/test_config.rb
|
33
|
+
- test/test_helper.rb
|
34
|
+
- test/test_test_case.rb
|
35
|
+
homepage: https://github.com/rickcarlino/doc_yo_self
|
36
|
+
licenses:
|
37
|
+
- MIT
|
38
|
+
metadata: {}
|
39
|
+
post_install_message:
|
40
|
+
rdoc_options: []
|
41
|
+
require_paths:
|
42
|
+
- lib
|
43
|
+
required_ruby_version: !ruby/object:Gem::Requirement
|
44
|
+
requirements:
|
45
|
+
- - '>='
|
46
|
+
- !ruby/object:Gem::Version
|
47
|
+
version: '0'
|
48
|
+
required_rubygems_version: !ruby/object:Gem::Requirement
|
49
|
+
requirements:
|
50
|
+
- - '>='
|
51
|
+
- !ruby/object:Gem::Version
|
52
|
+
version: '0'
|
53
|
+
requirements: []
|
54
|
+
rubyforge_project:
|
55
|
+
rubygems_version: 2.2.2
|
56
|
+
signing_key:
|
57
|
+
specification_version: 4
|
58
|
+
summary: Uses your test cases to write example documentation for your API.
|
59
|
+
test_files:
|
60
|
+
- test/fake_output.md
|
61
|
+
- test/fake_template.md
|
62
|
+
- test/test_base.rb
|
63
|
+
- test/test_config.rb
|
64
|
+
- test/test_helper.rb
|
65
|
+
- test/test_test_case.rb
|