smashing_docs 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 22b7029c0973147b6d3a28e53a5f3cab6c77b9a0
+  data.tar.gz: 0d6744dbb8ebdd8a92dccc1302bdd51c2100ddc9
+SHA512:
+  metadata.gz: bf8e59d70429b63875b0a3f405f26b598d644fd3dfc9a0cb8bc8f6dc0dd45e25d99711a11ba4ccb2a7b6e9260b56e31b2f5e37e267fa6d4e4df668437d11677b
+  data.tar.gz: 9ad103afe3b8f88ffa85ab7df2c0b716d9169f2134022b147855bb0e00d7d971e28220d6d66464d21880b12a9cc55834b2fad439ad477285cfd4f96e2a58fb9a

data/.gitignore

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

data/.rspec

@@ -0,0 +1 @@
+--color

data/README.md

@@ -0,0 +1,164 @@
+# SmashingDocs
+
+### Based on [SmarfDoc](https://github.com/RickCarlino/smarf_doc) by [Rick Carlino](https://github.com/RickCarlino/)
+
+## Gem Installation in Rails
+
+In your gemfile add the following to your test group:
+
+`gem 'smashing_docs', git: 'https://github.com/smashingboxes/smashing_docs.git'`
+
+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) { SmashingDocs.finish! }`
+
+It should look like this
+```ruby
+RSpec.configure do |config|
+  # Existing code
+  config.after(:suite) { SmashingDocs.finish! }
+end
+```
+#### To run on all controller tests
+
+Add this to your `spec_helper.rb`
+```ruby
+config.after(:each, type: :controller) do
+  SmashingDocs.run!(request, response)
+end
+```
+
+The whole file should look like this
+```ruby
+RSpec.configure do |config|
+  # Existing code
+  config.after(:each, type: :controller) do
+    SmashingDocs.run!(request, response)
+  end
+  config.after(:suite) { SmashingDocs.finish! }
+end
+```
+#### To run on only select tests
+Just add `SmashingDocs.run!(request, response)` to specific tests
+```ruby
+it "responds with 200" do
+  get :index
+  expect(response).to be_success
+  SmashingDocs.run!(request, response)
+end
+```
+
+## Minitest Installation
+
+Add the code from below to `test_helper.rb`:
+```ruby
+class ActiveSupport::TestCase
+  # Already existing code
+  SmashingDocs.config do |c|
+    c.template_file = 'test/template.md.erb'
+    c.output_file   = 'api_docs.md'
+  end
+  # More code
+end
+
+MiniTest::Unit.after_tests { SmashingDocs.finish! }
+```
+#### To run on all controller tests
+Add this to `test_helper.rb` as well:
+```ruby
+class ActionController::TestCase < ActiveSupport::TestCase
+  def teardown
+    SmashingDocs.run!(request, response)
+  end
+end
+```
+
+Your code should look like this:
+```ruby
+class ActiveSupport::TestCase
+  # Already existing code
+  SmashingDocs.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
+    SmashingDocs.run!(request, response)
+  end
+end
+
+MiniTest::Unit.after_tests { SmashingDocs.finish! }
+```
+
+
+#### To run on only select tests
+Just add `SmashingDocs.run!(request, response)` to specific tests
+```ruby
+def get_index
+  get :index
+  assert response.status == 200
+  SmashingDocs.run!(request, response)
+end
+```
+
+## Setting a template
+
+If you copied the code from above, SmashingDocs 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[:note] %>
+<%= aside %>
+```
+
+## 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 `SmashingDocs.skip` to the test.
+
+```ruby
+it "responds with 200" do
+  SmashingDocs.skip
+  # test code
+end
+```
+
+#### Adding information, e.g. notes
+SmashingDocs will log all requests and responses by default, but you can add some
+**optional** parameters as well.
+
+```ruby
+it "responds with 200" do
+  SmashingDocs.information(:note, "This endpoint only responds on Tuesdays")
+  # test code
+end
+```
+You can store any information with `:note`, `:message`, or any other key you can think of.
+To access information in the template, just use `<%= information[:key] %>`

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

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,99 @@
+class SmashingDocs
+  attr_accessor :tests
+  def initialize
+    @tests = []
+    @skip = false
+    @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 aside(msg)
+    @aside = ''
+    @aside = "<aside class='notice'>\n #{msg}\n</aside>"
+  end
+
+  def information(key, value)
+    @information[key] = value
+  end
+
+  def run!(request, response)
+    if @skip
+      @skip = false
+      return
+    end
+    add_test_case(request, response)
+    @information = {}
+    @skip = false
+    self
+  end
+
+  def add_test_case(request, response)
+    test = self.class::TestCase.new(request, response, @information, @aside)
+    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 SmashingDocs' 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
+
+# = = = =
+# These class methods are used to persist test data across tests
+# RSpec and Minitest do not support hooks that would allow
+# for an instance variable to be declared and used
+
+  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.information(key, value)
+    current.information(key, value)
+  end
+
+  def self.aside(message)
+    current.aside(message)
+  end
+
+  def self.current
+    # Behaves like an instance of SmashingDocs class
+    Thread.current[:instance] ||= self.new
+  end
+
+  def self.config(&block)
+    yield(self::Conf)
+  end
+end

data/lib/conf.rb

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

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

data/lib/test_case.rb

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

data/smashing_docs.gemspec

@@ -0,0 +1,18 @@
+$:.push File.expand_path('../lib', __FILE__)
+
+Gem::Specification.new do |s|
+  s.authors = ['Tyler Rockwell', 'Annie Baer', 'Rick Carlino']
+  s.description = "Write API documentation using existing controller tests."
+  s.files = `git ls-files`.split("\n")
+  s.homepage = 'https://github.com/smashingboxes/smashing_docs'
+  s.license = 'MIT'
+  s.name = 'smashing_docs'
+  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.2'
+
+  s.add_development_dependency "bundler", "~> 1.11"
+  s.add_development_dependency "rake", "~> 10.0"
+  s.add_development_dependency "rspec", "~> 3.0"
+end

data/spec/base_spec.rb

@@ -0,0 +1,92 @@
+require 'spec_helper'
+
+RSpec.describe SmashingDocs do
+  let(:file) { SmashingDocs::Conf.output_file }
+  let(:first) { Request.new("GET", {id: 12}, 'api/aaa') }
+  let(:middle) { Request.new("GET", { id: 12 }, 'api/ooo') }
+  let(:last) { Request.new("GET", {id: 12}, 'api/zzz') }
+  let(:tests) { SmashingDocs.current.tests }
+
+  describe ".run!(request, response)" do
+    context "when no tests have been run" do
+      it "has done nothing" do
+        expect(tests.length).to eq(0)
+      end
+    end
+    context "running 1 test" do
+      it "adds the test to the list of tests" do
+        SmashingDocs.run!(request, response)
+        expect(tests.length).to eq(1)
+        expect(tests.first).to be_a(SmashingDocs::TestCase)
+      end
+    end
+    context "running 2 tests" do
+      it "adds both tests to the list of tests" do
+        2.times { SmashingDocs.run!(request, response) }
+        expect(tests.length).to eq(2)
+      end
+    end
+  end
+
+  describe ".sort!" do
+    let(:results) { SmashingDocs.current.sort_by_url!.map{|tc| tc.request.path} }
+    it "sorts tests alphabetically by endpoint" do
+      SmashingDocs.run!(first, response)
+      SmashingDocs.run!(last, response)
+      SmashingDocs.run!(middle, response)
+      expect(results).to eq(["api/aaa", "api/ooo", "api/zzz"])
+    end
+  end
+
+  describe ".finish!" do
+    it "creates the docs file with output from the template" do
+      SmashingDocs.run!(first, response)
+      SmashingDocs.run!(last, response)
+      SmashingDocs.finish!
+      expect(File).to exist(file)
+      expect(File.read(file)).to include("You can use ERB")
+    end
+  end
+
+  describe ".skip" do
+    context "one skip" do
+      it "skips a single test" do
+        SmashingDocs.skip
+        SmashingDocs.run!(first, response)
+        SmashingDocs.run!(last, response)
+        expect(tests.length).to eq(1)
+        expect(tests.first.request.path).to eq("api/zzz")
+      end
+    end
+    context "multiple skips" do
+      it "skips multiple tests" do
+        SmashingDocs.skip
+        SmashingDocs.run!(first, response)
+        SmashingDocs.skip
+        SmashingDocs.run!(middle, response)
+        SmashingDocs.run!(last, response)
+        expect(tests.length).to eq(1)
+        expect(tests.first.request.path).to eq("api/zzz")
+      end
+    end
+  end
+
+  describe ".information(key, value)" do
+    # The template file must have <%= information[:note] %>
+    it "sends information to be displayed about the endpoint" do
+      SmashingDocs.information(:note, "Endpoint note")
+      SmashingDocs.run!(first, response)
+      expect(tests.first.compile_template).to include("Endpoint note")
+    end
+  end
+
+  describe ".aside(message)" do
+    # The template file must have <%= information[:note] %>
+    it "sends information to be displayed about the endpoint" do
+      SmashingDocs.aside("I am an aside")
+      SmashingDocs.run!(first, response)
+      expect(tests.first.compile_template).to include("<aside class='notice'>")
+      expect(tests.first.compile_template).to include("I am an aside")      
+    end
+  end
+end

data/spec/conf_spec.rb

@@ -0,0 +1,17 @@
+require 'spec_helper'
+
+RSpec.describe SmashingDocs::Conf do
+  let!(:config) {
+    SmashingDocs.config do |c|
+      c.template_file = "spec/template.md.erb"
+      c.output_file   = "api_docs.md"
+    end
+  }
+  it "sets the template file" do
+    expect(SmashingDocs::Conf.output_file).to eq("api_docs.md")
+  end
+
+  it "sets the output file" do
+    expect(SmashingDocs::Conf.template_file).to eq("spec/template.md.erb")
+  end
+end

data/spec/fake_template.md.erb

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

data/spec/spec_helper.rb

@@ -0,0 +1,29 @@
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+require 'smashing_docs'
+
+RSpec.configure do |config|
+  config.expect_with :rspec do |expectations|
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+  config.before(:each) do
+    SmashingDocs.config do |c|
+      c.template_file = 'spec/fake_template.md.erb'
+      c.output_file   = 'spec/fake_output.md'
+    end
+  end
+  config.after(:each) do
+    SmashingDocs.finish!
+  end
+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

data/spec/test_case_spec.rb

@@ -0,0 +1,29 @@
+require 'spec_helper'
+
+RSpec.describe SmashingDocs::TestCase do
+  let(:test_case) { SmashingDocs::TestCase.new(request, response) }
+
+  describe "#compile_template" do
+    context "with text" do
+      let(:template) { "<%= 2 + 2 %>" }
+      it "evaluates erb and returns a value" do
+        test_case.template = template
+        expect(test_case.compile_template).to eq("4")
+      end
+    end
+
+    context "with a template file" do
+      let!(:template) { SmashingDocs.config { |c| c.template_file = 'spec/fake_template.md.erb' } }
+      it "sets the template file and returns docs matching the template" do
+        test_case.template = SmashingDocs::Conf.template
+        expect(test_case.compile_template).to include("use ERB")
+      end
+    end
+  end
+
+  describe "#created_at" do
+    it "returns the time the TestCase was created" do
+      expect(test_case.created_at).to be_a(Time)
+    end
+  end
+end

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification
+name: smashing_docs
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+platform: ruby
+authors:
+- Tyler Rockwell
+- Annie Baer
+- Rick Carlino
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-02-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Write API documentation using existing controller tests.
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- README.md
+- Rakefile
+- api_docs.md
+- documentation.md
+- lib/base.rb
+- lib/conf.rb
+- lib/smashing_docs.rb
+- lib/test_case.rb
+- smashing_docs.gemspec
+- spec/base_spec.rb
+- spec/conf_spec.rb
+- spec/fake_output.md
+- spec/fake_template.md.erb
+- spec/spec_helper.rb
+- spec/test_case_spec.rb
+homepage: https://github.com/smashingboxes/smashing_docs
+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.5
+signing_key: 
+specification_version: 4
+summary: Uses your test cases to write example documentation for your API.
+test_files:
+- spec/base_spec.rb
+- spec/conf_spec.rb
+- spec/fake_output.md
+- spec/fake_template.md.erb
+- spec/spec_helper.rb
+- spec/test_case_spec.rb