smarf_doc 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 035b5d1410143ff9b925041dfe1ac3b1ced0fe95
+  data.tar.gz: 835909a904ab7d01fcb169d2369a81245c357c53
+SHA512:
+  metadata.gz: 8e136d5bf18e873e74e044a15f32f226e17f893121a7d62889a7b5332a962256a95a55a2dabeebdaa335ca8b9963890abb42fdcc185fb0fd5dbb9ce928104908
+  data.tar.gz: a40c8a9b9df76935feffffb355fdd87ab9711c6743a7626db1dd95436f6612e94fc24558773851f019674b126af6b96b3b78f4fd517287847057beadacd6d042

data/.gitignore

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

data/README.md

@@ -0,0 +1,183 @@
+# SmarfDoc
+
+(Formerly 'DocYoSelf')
+
+![Smarf](http://i.imgur.com/f5mzeRU.png)
+
+Too many docs spoil the broth.
+
+SmarfDoc lets you turn your controller tests into API docs _without making changes to your test suite or how you write tests_.
+
+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!
+
+
+## Gem Installation in Rails
+
+In your gemfile add the following to your test group:
+
+`gem 'smarf_doc', group: :test, github: 'RickCarlino/smarf_doc'`
+
+Installation differs for RSpec/Minitest, so scroll to the appropriate section for guidance.
+
+## Rspec Installation
+
+Add this to your `rails_helper.rb` It should go outside of other blocks
+(Do not place it inside the `RSpec.configure` block).
+```ruby
+SmarfDoc.config do |c|
+  c.template_file = 'spec/template.md.erb'
+  c.output_file   = 'api_docs.md'
+end
+```
+
+Add the following line to `spec_helper.rb` inside the `RSpec.configure` block
+
+`config.after(:suite) { SmarfDoc.finish! }`
+
+It should look like this
+```ruby
+RSpec.configure do |config|
+  # Existing code
+  config.after(:suite) { SmarfDoc.finish! }
+end
+```
+#### To run on all controller tests
+
+Add this to your `spec_helper.rb`
+```ruby
+config.after(:each, type: :controller) do
+  SmarfDoc.run!(request, response)
+end
+```
+
+The whole file should look like this
+```ruby
+RSpec.configure do |config|
+  # Existing code
+  config.after(:each, type: :controller) do
+    SmarfDoc.run!(request, response)
+  end
+  config.after(:suite) { SmarfDoc.finish! }
+end
+```
+#### To run on only select tests
+Just add `SmarfDoc.run!(request, response)` to specific tests
+```ruby
+it "responds with 200" do
+  get :index
+  expect(response).to be_success
+  SmarfDoc.run!(request, response)
+end
+```
+
+## Minitest Installation
+
+Add the code from below to `test_helper.rb`:
+```ruby
+class ActiveSupport::TestCase
+  # Already existing code
+  SmarfDoc.config do |c|
+    c.template_file = 'test/template.md.erb'
+    c.output_file   = 'api_docs.md'
+  end
+  # More code
+end
+
+MiniTest::Unit.after_tests { SmarfDoc.finish! }
+```
+#### To run on all controller tests
+Add this to `test_helper.rb` as well:
+```ruby
+class ActionController::TestCase < ActiveSupport::TestCase
+  def teardown
+    SmarfDoc.run!(request, response)
+  end
+end
+```
+
+Your code should look like this:
+```ruby
+class ActiveSupport::TestCase
+  # Already existing code
+  SmarfDoc.config do |c|
+    c.template_file = 'test/template.md.erb'
+    c.output_file   = 'api_docs.md'
+  end
+  # More code
+end
+
+class ActionController::TestCase < ActiveSupport::TestCase
+  def teardown
+    SmarfDoc.run!(request, response)
+  end
+end
+
+MiniTest::Unit.after_tests { SmarfDoc.finish! }
+```
+
+
+#### To run on only select tests
+Just add `SmarfDoc.run!(request, response)` to specific tests
+```ruby
+def get_index
+  get :index
+  assert response.status == 200
+  SmarfDoc.run!(request, response)
+end
+```
+
+## Setting a template
+
+If you copied the code from above, SmarfDoc will look for a template file located at either
+`test/template.md.erb` or `spec/template.md.erb`, depending on your test suite.
+This template may be customized to fit your needs.
+
+```erb
+<%= request.method %>
+<%= request.path %>
+<%= request.params %>
+<%= response.body %>
+<%= information[:message] %>
+<%= note %>
+```
+
+## Where to find the docs
+
+By default, the docs are output to `api_docs.md` in the root of the Rails project.
+You can change this by altering the config in `test_helper.rb` or `rails_helper.rb`.
+
+## Additional Features
+
+#### Skipping documentation on tests
+
+To leave certain tests out of the documentation, just add `SmarfDoc.skip` to the test.
+
+```ruby
+it "responds with 200" do
+  SmarfDoc.skip
+  # test code
+end
+```
+
+#### Adding information and notes
+SmarfDoc will log all requests and responses by default, but you can add some
+**optional** parameters as well.
+
+```ruby
+it "responds with 200" do
+  SmarfDoc.note("This endpoint prefers butterscotch")
+  # test code
+end
+```
+#### OR
+```ruby
+it "responds with 200" do
+  SmarfDoc.information(:message, "This endpoint only responds on Tuesdays")
+  # test code
+end
+```
+
+You can store any information with `:message` or any other key you can think of.
+To access information in the template, just use `<%= information[:message] %>`

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/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,94 @@
+class SmarfDoc
+  attr_accessor :tests
+  def initialize
+    @tests = []
+    @skip = false
+    @note = ''
+    @information = {}
+  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 information(key, value)
+    @information[key] = value
+  end
+
+  def run!(request, response)
+    if @skip
+      @skip = false
+      return
+    end
+    add_test_case(request, response)
+    @note = ''
+    self
+  end
+
+  def add_test_case(request, response)
+    test = self.class::TestCase.new(request, response, @note, @information)
+    test.template = self.class::Conf.template
+    self.tests << test
+  end
+
+  def skip
+    @skip = true
+  end
+
+  def output_testcases_to_file
+    docs = self.class::Conf.output_file
+    raise 'No output file specific for SmarfDoc' 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.information(key, value)
+    current.information(key, value)
+  end
+
+  def self.current
+    Thread.current[:instance] ||= self.new
+  end
+
+  def self.config(&block)
+    yield(self::Conf)
+  end
+end

data/lib/conf.rb

@@ -0,0 +1,12 @@
+class SmarfDoc::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/smarf_doc.rb

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

data/lib/test_case.rb

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

data/smarf_doc.gemspec

@@ -0,0 +1,15 @@
+$:.push File.expand_path('../lib', __FILE__)
+
+Gem::Specification.new do |s|
+  s.authors = ['Rick Carlino']
+  s.description = "Write API documentation using existing controller tests."
+  s.email = 'rick.carlino@gmail.com'
+  s.files = `git ls-files`.split("\n")
+  s.homepage = 'https://github.com/RickCarlino/smarf_doc'
+  s.license = 'MIT'
+  s.name = 'smarf_doc'
+  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 = '1.0.0'
+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 %>
+<%= information[:aside] %>

data/test/test_base.rb

@@ -0,0 +1,102 @@
+require_relative "test_helper"
+
+class TestBase < SmarfDocTest
+
+  def test_run!
+    tests = SmarfDoc.current.tests
+    assert_equal 0, tests.length,
+      "Expected current tests to be an empty array"
+    SmarfDoc.run!(request, response)
+    assert_equal 1, tests.length,
+      "Expected run!() to increase number of tests"
+    assert tests.first.is_a?(SmarfDoc::TestCase)
+    SmarfDoc.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')
+    SmarfDoc.run!(first, response)
+    SmarfDoc.run!(last, response)
+    results = SmarfDoc.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 = SmarfDoc::Conf.output_file
+    first = Request.new("GET", {id: 12}, 'api/aaa')
+    last  = Request.new("GET", {id: 12}, 'api/zzz')
+    SmarfDoc.run!(first, response)
+    SmarfDoc.run!(last, response)
+    SmarfDoc.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 = SmarfDoc::Conf.output_file
+    tests= SmarfDoc.current.tests
+    first = Request.new("GET", {id: 12}, 'api/skip')
+    last  = Request.new("GET", {id: 12}, 'api/noskip')
+    SmarfDoc.skip
+    SmarfDoc.run!(first, response)
+    SmarfDoc.run!(last, response)
+    assert_equal 1, tests.length,
+      "Did not skip tests."
+    assert_equal 'api/noskip', tests.first.request.path,
+      "Did not skip tests."
+  end
+
+  def test_multiple_skips
+    file = SmarfDoc::Conf.output_file
+    tests= SmarfDoc.current.tests
+    first = Request.new("GET", {id: 12}, 'api/noskip1')
+    second = Request.new("GET", {id: 12}, 'api/skip1')
+    third  = Request.new("GET", {id: 12}, 'api/skip2')
+    fourth  = Request.new("GET", {id: 12}, 'api/noskip2')
+    SmarfDoc.run!(first, response)
+    SmarfDoc.skip
+    SmarfDoc.run!(second, response)
+    SmarfDoc.skip
+    SmarfDoc.run!(third, response)
+    SmarfDoc.run!(fourth, response)
+    assert_equal 2, tests.length,
+      "Skipped 2 tests."
+    assert_equal 'api/noskip1', tests[0].request.path,
+      "Did not skip first unskipped test."
+    assert_equal 'api/noskip2', tests[1].request.path,
+      "Did not skip second unskipped test."
+  end
+
+  def test_note
+    file = SmarfDoc::Conf.output_file
+    tests= SmarfDoc.current.tests
+    first = Request.new("GET", {id: 12}, 'api/skip')
+    last  = Request.new("GET", {id: 12}, 'api/noskip')
+    SmarfDoc.note "안녕하세요"
+    SmarfDoc.run!(first, response)
+    SmarfDoc.run!(last, response)
+    assert_includes tests.first.compile_template, "안녕하세요",
+      "Could not find note in documentation."
+  end
+
+  def test_information
+    file = SmarfDoc::Conf.output_file
+    tests= SmarfDoc.current.tests
+    first = Request.new("GET", {id: 12}, 'api/skip')
+    last  = Request.new("GET", {id: 12}, 'api/noskip')
+    SmarfDoc.information(:aside, "This controller only responds on Tuesdays")
+    SmarfDoc.run!(first, response)
+    SmarfDoc.run!(last, response)
+    assert_includes tests.first.compile_template, "This controller only responds on Tuesdays",
+      "Could not find note in documentation."
+  end
+end

data/test/test_config.rb

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

data/test/test_helper.rb

@@ -0,0 +1,29 @@
+require_relative '../lib/smarf_doc'
+require 'minitest/autorun'
+require 'minitest/pride'
+require 'pry'
+
+class SmarfDocTest < Minitest::Test
+  def setup
+    SmarfDoc.config do |c|
+      c.template_file = 'test/fake_template.md'
+      c.output_file   = 'test/fake_output.md'
+    end
+  end
+
+  def teardown
+    SmarfDoc.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 < SmarfDocTest
+
+  def test_case
+    @test_case ||= SmarfDoc::TestCase.new(request, response)
+  end
+
+  def test_compile_template
+    template = "<%= 2 + 2 %>"
+    test_case.template = template
+    assert_equal test_case.template, template,
+      "Could not set a template."
+    assert_equal "4", test_case.compile_template,
+      "Could not compile template"
+  end
+
+  def test_compile_with_file
+    SmarfDoc.config { |c| c.template_file = 'test/fake_template.md' }
+    test = SmarfDoc::TestCase.new(request, response)
+    test.template = SmarfDoc::Conf.template
+    assert_includes test.compile_template, "use ERB"
+  end
+
+  def test_created_at
+    assert test_case.created_at.is_a?(Time)
+  end
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification
+name: smarf_doc
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Rick Carlino
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-02-21 00:00:00.000000000 Z
+dependencies: []
+description: Write API documentation using existing controller tests.
+email: rick.carlino@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- README.md
+- Rakefile
+- api_docs.md
+- documentation.md
+- lib/base.rb
+- lib/conf.rb
+- lib/smarf_doc.rb
+- lib/test_case.rb
+- smarf_doc.gemspec
+- 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/smarf_doc
+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.4.8
+signing_key: 
+specification_version: 4
+summary: Uses your test cases to write example documentation for your API.
+test_files: []