doc_yo_self 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1dca5880b129ed713c81bfecb1ea14cc0b9626d7
+  data.tar.gz: f4f71b07c337878360beaae7bd95704646e39356
+SHA512:
+  metadata.gz: 0a0163819d7f45e25692402dab3a108487ad1978eae2c8e4b9b8184b9b46e9c2d403af65c07d2394d6baa57d65a93f5f00f43ec885efa1fbf33c540534e3c68d
+  data.tar.gz: d8abe36cc4aec720b51bf12a1136ab9785dab713780c00b45324c7196d79851a09ceee84548b53263b2a8dd2766d996476bcb3f02d9bf84515abb3168ba76f1a

data/.gitignore

@@ -0,0 +1 @@
+/coverage/

data/README.md

@@ -0,0 +1,66 @@
+# Doc Yo Self
+
+An auto documentation for Rails. Pop it into your test suite and watch it amaze.
+
+Time for this project was provided by my employer, [SmashingBoxes](http://smashingboxes.com/). What a great place to work.
+
+# Limitations
+
+ * **Current focus is MiniTest**. Probably will work with Rspec too, but that's not our focus right now.
+ * **Probably not thread safe**. Thread safety isn't a focus for this project right now. Pull requests welcome :-).
+
+
+## Setup
+
+```ruby
+DocYoSelf.config do |c|
+  c.template_file = 'test/template.md.erb'
+  c.output        = 'api_docs.md'
+end
+```
+
+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*.
+
+```ruby
+def teardown
+  DocYoSelf.run!
+end 
+```
+
+Then put this at the bottom of your `test_helper.rb`:
+
+```ruby
+DocYoSelf.finish!
+```
+
+Or put it individually into only certain tests...
+
+```ruby
+def test_some_api
+  get :index, :users
+  assert response.status == 200
+  DocYoSelf.run!
+end
+```
+
+## Usage
+
+It will log all requests and responses by default, but you can add some **optional** parameters as well.
+
+### Skipping documentation
+
+```ruby
+def test_stuff
+  DocYoSelf.skip
+  # Blahhh
+end
+```
+
+## Adding notes
+
+```ruby
+def test_stuff
+  DocYoSelf.note "안녕하세요. This is a note."
+  # Blahhh
+end
+```

data/Rakefile

@@ -0,0 +1,8 @@
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+end
+
+desc "Run tests"
+task :default => :test

data/doc_yo_self.gemspec

@@ -0,0 +1,15 @@
+$:.push File.expand_path('../lib', __FILE__)
+
+Gem::Specification.new do |s|
+  s.authors = ['Rick Carlino']
+  s.description = "An automatic API documentation generator."
+  s.email = 'rick.carlino@gmail.com'
+  s.files = `git ls-files`.split("\n")
+  s.homepage = 'https://github.com/rickcarlino/doc_yo_self'
+  s.license = 'MIT'
+  s.name = 'doc_yo_self'
+  s.require_paths = ['lib']
+  s.summary = "Uses your test cases to write example documentation for your API."
+  s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.version = '0.0.1'
+end

data/documentation.md

@@ -0,0 +1,80 @@
+You can use ERB to format each test case.
+GET
+api/aaa
+{:id=>12}
+{"id": 12, "name": "rick"}
+You can use ERB to format each test case.
+GET
+api/users
+{:id=>12}
+{"id": 12, "name": "rick"}
+You can use ERB to format each test case.
+GET
+api/users
+{:id=>12}
+{"id": 12, "name": "rick"}
+You can use ERB to format each test case.
+GET
+api/zzz
+{:id=>12}
+{"id": 12, "name": "rick"}
+You can use ERB to format each test case.
+GET
+api/aaa
+{:id=>12}
+{"id": 12, "name": "rick"}
+You can use ERB to format each test case.
+GET
+api/users
+{:id=>12}
+{"id": 12, "name": "rick"}
+You can use ERB to format each test case.
+GET
+api/users
+{:id=>12}
+{"id": 12, "name": "rick"}
+You can use ERB to format each test case.
+GET
+api/zzz
+{:id=>12}
+{"id": 12, "name": "rick"}
+You can use ERB to format each test case.
+GET
+api/aaa
+{:id=>12}
+{"id": 12, "name": "rick"}
+You can use ERB to format each test case.
+GET
+api/zzz
+{:id=>12}
+{"id": 12, "name": "rick"}
+You can use ERB to format each test case.
+GET
+api/users
+{:id=>12}
+{"id": 12, "name": "rick"}
+You can use ERB to format each test case.
+GET
+api/users
+{:id=>12}
+{"id": 12, "name": "rick"}
+You can use ERB to format each test case.
+GET
+api/aaa
+{:id=>12}
+{"id": 12, "name": "rick"}
+You can use ERB to format each test case.
+GET
+api/zzz
+{:id=>12}
+{"id": 12, "name": "rick"}
+You can use ERB to format each test case.
+GET
+api/aaa
+{:id=>12}
+{"id": 12, "name": "rick"}
+You can use ERB to format each test case.
+GET
+api/zzz
+{:id=>12}
+{"id": 12, "name": "rick"}

data/lib/base.rb

@@ -0,0 +1,83 @@
+class DocYoSelf
+  attr_accessor :tests
+  def initialize
+    @tests = []
+    @skip = 0 # <= Hate this.
+  end
+
+  def sort_by_url!
+    @tests.sort! do |x, y|
+      x.request.path <=> y.request.path
+    end
+  end
+
+  def clean_up!
+    @tests = []
+  end
+
+  def note(msg)
+    @note = msg || ''
+  end
+
+  def run!(request, response)
+    @skip += 1
+    return if @skip == 2 # Gross.
+    add_test_case(request, response, @note)
+    @note = ''
+    @skip = 0
+    self
+  end
+
+  def add_test_case(request, response, note)
+    test = self.class::TestCase.new(request, response, note)
+    test.template = self.class::Conf.template
+    self.tests << test
+  end
+
+  def skip
+    @skip += 1
+  end
+
+  def output_testcases_to_file
+    docs = self.class::Conf.output_file
+    raise 'No output file specific for DocYoSelf' unless docs
+    File.delete docs if File.exists? docs
+    write_to_file
+  end
+
+  def write_to_file
+    File.open(self.class::Conf.output_file, 'a') do |file|
+      @tests.each do |test|
+        file.write(test.compile_template)
+      end
+    end
+  end
+
+# = = = =
+
+  def self.finish!
+    current.sort_by_url!
+    current.output_testcases_to_file
+    current.clean_up!
+  end
+
+  def self.run!(request, response)
+    current.run!(request, response)
+  end
+
+  def self.skip
+    current.skip
+  end
+
+  def self.note(msg)
+    current.note(msg)
+  end
+
+  def self.current
+    Thread.current[:dys_instance] ||= self.new
+  end
+
+  def self.config(&block)
+    yield(self::Conf)
+  end
+end

data/lib/conf.rb

@@ -0,0 +1,12 @@
+class DocYoSelf::Conf
+  class << self
+    attr_accessor :template_file, :output_file
+
+    @output_file = 'documentation.md'
+
+    def template
+      raise 'You must set a template file.' unless template_file
+      @template ||= File.read(template_file)
+    end
+  end
+end

data/lib/doc_yo_self.rb

@@ -0,0 +1,4 @@
+require 'base'
+require 'conf'
+require 'test_case'
+

data/lib/test_case.rb

@@ -0,0 +1,15 @@
+require 'erb'
+
+class DocYoSelf::TestCase
+  attr_reader :request, :response, :created_at, :note
+  attr_accessor :template
+
+  def initialize(request, response, note = '')
+    @request, @response, @note = request, response, note
+    @created_at         = Time.now
+  end
+
+  def compile_template
+    ERB.new(template).result binding
+  end
+end

data/test/fake_template.md

@@ -0,0 +1,7 @@
+You can use ERB to format each test case.
+<%= request.method %>
+<%= request.path %>
+<%= request.params %>
+<%= response.body %>
+<%= note %>
+

data/test/test_base.rb

@@ -0,0 +1,69 @@
+require_relative "test_helper"
+
+class TestBase < DysTest
+
+  def test_run!
+    tests = DocYoSelf.current.tests
+    assert_equal 0, tests.length,
+      "Expected current tests to be an empty array"
+    DocYoSelf.run!(request, response)
+    assert_equal 1, tests.length,
+      "Expected run!() to increase number of tests"
+    assert tests.first.is_a?(DocYoSelf::TestCase)
+    DocYoSelf.run!(request, response)
+    assert_equal 2, tests.length,
+      "Expected run!() to increase number of tests"
+    assert_includes tests.first.compile_template,
+        "You can use ERB to format each test case",
+        "Did not load correct template file"
+  end
+
+  def test_sort!
+    first = Request.new("GET", {id: 12}, 'api/aaa')
+    last  = Request.new("GET", {id: 12}, 'api/zzz')
+    DocYoSelf.run!(first, response)
+    DocYoSelf.run!(last, response)
+    results = DocYoSelf.current.sort_by_url!.map{|tc| tc.request.path}
+    assert_equal ["api/aaa", "api/zzz"], results,
+      "Did not sort test cases by request URL"
+  end
+
+  def test_finish!
+    file = DocYoSelf::Conf.output_file
+    first = Request.new("GET", {id: 12}, 'api/aaa')
+    last  = Request.new("GET", {id: 12}, 'api/zzz')
+    DocYoSelf.run!(first, response)
+    DocYoSelf.run!(last, response)
+    DocYoSelf.finish!
+    assert File.exists?(file),
+      "Did not create an output file after finish!()ing"
+    assert_includes File.read(file), "You can use ERB",
+      "Did not utilize template to output docs."
+  end
+
+  def test_skip
+    file = DocYoSelf::Conf.output_file
+    tests= DocYoSelf.current.tests
+    first = Request.new("GET", {id: 12}, 'api/skip')
+    last  = Request.new("GET", {id: 12}, 'api/noskip')
+    DocYoSelf.skip
+    DocYoSelf.run!(first, response)
+    DocYoSelf.run!(last, response)
+    assert_equal 1, tests.length,
+      "DYS Did not skip tests."
+    assert_equal 'api/noskip', tests.first.request.path,
+      "DYS Did not skip tests."
+  end
+
+  def test_note
+    file = DocYoSelf::Conf.output_file
+    tests= DocYoSelf.current.tests
+    first = Request.new("GET", {id: 12}, 'api/skip')
+    last  = Request.new("GET", {id: 12}, 'api/noskip')
+    DocYoSelf.note "안녕하세요"
+    DocYoSelf.run!(first, response)
+    DocYoSelf.run!(last, response)
+    assert_includes tests.first.compile_template, "안녕하세요",
+      "Could not find note in documentation."
+  end
+end

data/test/test_config.rb

@@ -0,0 +1,15 @@
+require_relative "test_helper"
+
+class TestConfig < DysTest
+
+  def test_set_configs
+    DocYoSelf.config do |c|
+      c.template_file = 'test/template.md.erb'
+      c.output_file   = 'api_docs.md'
+    end
+    assert_equal 'api_docs.md', DocYoSelf::Conf.output_file,
+      "Unable to set output file"
+    assert_equal 'test/template.md.erb', DocYoSelf::Conf.template_file,
+      "Unable to set template file"
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,30 @@
+require "simplecov"
+SimpleCov.start
+require_relative '../lib/doc_yo_self'
+require 'minitest/autorun'
+require 'pry'
+
+class DysTest < Minitest::Unit::TestCase
+  def setup
+    DocYoSelf.config do |c|
+      c.template_file = 'test/fake_template.md'
+      c.output_file   = 'test/fake_output.md'
+    end
+  end
+
+  def teardown
+    DocYoSelf.finish!
+  end
+
+  # Include some fake structs that act like response/request objects.
+  Request  = Struct.new :method, :params, :path
+  Response = Struct.new :body, :success?
+
+  def request
+    Request.new("GET", {id: 12}, 'api/users')
+  end
+
+  def response
+    Response.new('{"id": 12, "name": "rick"}', true)
+  end
+end

data/test/test_test_case.rb

@@ -0,0 +1,28 @@
+require_relative "test_helper"
+
+class TestTestCase < DysTest
+
+  def dys
+    @dys ||= DocYoSelf::TestCase.new(request, response)
+  end
+
+  def test_compile_template
+    template     = "<%= 2 + 2 %>"
+    dys.template = template
+    assert_equal dys.template, template,
+      "Could not set a template."
+    assert_equal "4", dys.compile_template,
+      "Could not compile template"
+  end
+
+  def test_compile_with_file
+    DocYoSelf.config { |c| c.template_file = 'test/fake_template.md' }
+    test = DocYoSelf::TestCase.new(request, response)
+    test.template = DocYoSelf::Conf.template
+    assert_includes test.compile_template, "use ERB"
+  end
+
+  def test_created_at
+    assert dys.created_at.is_a?(Time)
+  end
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: doc_yo_self
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Rick Carlino
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-08-29 00:00:00.000000000 Z
+dependencies: []
+description: An automatic API documentation generator.
+email: rick.carlino@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- README.md
+- Rakefile
+- api_docs.md
+- doc_yo_self.gemspec
+- documentation.md
+- lib/base.rb
+- lib/conf.rb
+- lib/doc_yo_self.rb
+- lib/test_case.rb
+- test/fake_output.md
+- test/fake_template.md
+- test/test_base.rb
+- test/test_config.rb
+- test/test_helper.rb
+- test/test_test_case.rb
+homepage: https://github.com/rickcarlino/doc_yo_self
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Uses your test cases to write example documentation for your API.
+test_files:
+- test/fake_output.md
+- test/fake_template.md
+- test/test_base.rb
+- test/test_config.rb
+- test/test_helper.rb
+- test/test_test_case.rb