smashing_docs 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 51d3931b8339c80e86f365d38579ca206aaec9e6
-  data.tar.gz: ef9f7460e973252cf1d722423d5b201de50ec238
+  metadata.gz: 31bc78abe84edc9c4717b1b0d1c792c23cef3cdc
+  data.tar.gz: 8f1dce8a1fd1be5e34512a7ac4c2847142d6881e
 SHA512:
-  metadata.gz: d9d6a0a33ee29cdbf5b22ba8b2fbd7235274cb36b4e81b96a4e6af76de8bf72d19f7acf474369c1de77ee2eb245d36ee626c910d785ee13ffb3d7e7d8722c18e
-  data.tar.gz: 2e8b0895112ea255a09a3cbebed9a747fbdd2a19e4ff7d7864dcb5d1aa9de4f238481119addd7c3c8b2a2a8801e7105ced9ed558f90e361e7d97ecece0dd8c5c
+  metadata.gz: 59e40621f291e1b6af8e0cff399de36ef81c0c6ac20e2c41b00c43e6c6b6d64b47c40dab566816ae2eaa659618057a41108fcaad5ac6f60fd5ac86b4b9300778
+  data.tar.gz: 1b32b71daeba769df485cd1318da17c877f9444981956df1b7837aac5b06f83b539620a93e3a216ad176735cbe239be8794d4932609669e3ba228dcd573ec55d

data/README.md

@@ -26,12 +26,13 @@ Add this to your `rails_helper.rb` It should go outside of other blocks
 (Do not place it inside the `RSpec.configure` block).
 ```ruby
 SmashingDocs.config do |c|
-  c.template_file = 'spec/template.md.erb'
-  c.output_file   = 'api_docs.md'
+  c.template_file = 'smashing_docs/template.md'
+  c.output_file   = 'smashing_docs/api_docs.md'
+  c.run_all       = true
 end
 ```
 
-Add the following line to `spec_helper.rb` inside the `RSpec.configure` block
+Add the following content to `spec_helper.rb` inside the `RSpec.configure` block
 
 `config.after(:suite) { SmashingDocs.finish! }`
 
@@ -39,30 +40,24 @@ It should look like this
 ```ruby
 RSpec.configure do |config|
   # Existing code
+  config.after(:each, type: :controller) do
+    SmashingDocs.run!(request, response, true)
+  end
   config.after(:suite) { SmashingDocs.finish! }
 end
 ```
-#### To run on all controller tests
 
-Add this to your `spec_helper.rb`
+#### To run on only select tests
+Set the `c.run_all` line to `false` in `rails_helper.rb`
 ```ruby
-config.after(:each, type: :controller) do
-  SmashingDocs.run!(request, response)
+SmashingDocs.config do |c|
+  c.template_file = 'smashing_docs/template.md'
+  c.output_file   = 'smashing_docs/api_docs.md'
+  c.run_all       = false
 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
+Then just add `SmashingDocs.run!(request, response)` to the tests you want to run
 ```ruby
 it "responds with 200" do
   get :index
@@ -78,47 +73,33 @@ Add the code from below to `test_helper.rb`:
 class ActiveSupport::TestCase
   # Already existing code
   SmashingDocs.config do |c|
-    c.template_file = 'test/template.md.erb'
-    c.output_file   = 'api_docs.md'
+    c.template_file = 'smashing_docs/template.md'
+    c.output_file   = 'smashing_docs/api_docs.md'
+    c.run_all       = true
   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)
+    SmashingDocs.run!(request, response, true)
   end
 end
+
+MiniTest::Unit.after_tests { SmashingDocs.finish! }
 ```
 
-Your code should look like this:
+#### To run on only select tests
+Set the `c.run_all` line to `false` in `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
-
-class ActionController::TestCase < ActiveSupport::TestCase
-  def teardown
-    SmashingDocs.run!(request, response)
-  end
+SmashingDocs.config do |c|
+  c.template_file = 'smashing_docs/template.md'
+  c.output_file   = 'smashing_docs/api_docs.md'
+  c.run_all       = false
 end
-
-MiniTest::Unit.after_tests { SmashingDocs.finish! }
 ```
 
-
-#### To run on only select tests
-Just add `SmashingDocs.run!(request, response)` to specific tests
+Then just add `SmashingDocs.run!(request, response)` to specific tests
 ```ruby
 def get_index
   get :index
@@ -129,8 +110,9 @@ 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.
+If you copied the code from above, SmashingDocs will look for a template file located in
+`smashing_docs/template.md`
+
 This template may be customized to fit your needs.
 
 ```erb
@@ -139,7 +121,6 @@ This template may be customized to fit your needs.
 <%= request.params %>
 <%= response.body %>
 <%= information[:note] %>
-<%= aside %>
 ```
 
 ## Where to find the docs

data/gem_rspec/base_spec.rb

@@ -8,22 +8,41 @@ RSpec.describe SmashingDocs do
   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)
+    context "when run_all config is set to true" do
+      context "when no tests have been run" do
+        it "has done nothing" do
+          expect(tests.length).to eq(0)
+        end
       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)
+      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
-    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)
+
+    context "when run_all config is set to false" do
+      context "tests triggered by RSpec after hook" do
+        it "does not add the tests" do
+          SmashingDocs::Conf.run_all = false
+          SmashingDocs.run!(request, response, true)
+          expect(tests.length).to eq(0)
+        end
+      end
+      context "tests added by the user" do
+        it "adds the tests" do
+          SmashingDocs::Conf.run_all = false
+          SmashingDocs.run!(request, response)
+          expect(tests.length).to eq(1)
+        end
       end
     end
   end
@@ -48,6 +67,21 @@ RSpec.describe SmashingDocs do
         expect(File.read(file)).to include("You can use ERB")
       end
     end
+    context "when there are no tests" do
+      it "does not overwrite the docs with an empty file" do
+        # Generate docs
+        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")
+
+        SmashingDocs.current.tests = []
+        SmashingDocs.finish!
+        expect(File).to exist(file)
+        expect(File.read(file)).to include("You can use ERB")
+      end
+    end
   end
 
   describe ".skip" do
@@ -81,14 +115,4 @@ RSpec.describe SmashingDocs do
       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/gem_rspec/conf_spec.rb

@@ -5,6 +5,7 @@ RSpec.describe SmashingDocs::Conf do
     SmashingDocs.config do |c|
       c.template_file = "gem_spec/fake_template.md.erb"
       c.output_file   = "api_docs.md"
+      c.run_all       = true
     end
   }
   it "sets the output file" do
@@ -14,4 +15,8 @@ RSpec.describe SmashingDocs::Conf do
   it "sets the template file" do
     expect(SmashingDocs::Conf.template_file).to eq("gem_spec/fake_template.md.erb")
   end
+
+  it "sets run_all" do
+    expect(SmashingDocs::Conf.run_all).to eq(true)
+  end
 end

data/gem_rspec/fake_output.md

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

data/gem_rspec/fake_template.md.erb

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

data/gem_rspec/test_case_spec.rb

@@ -13,7 +13,7 @@ RSpec.describe SmashingDocs::TestCase do
     end
 
     context "with a template file" do
-      let!(:template) { SmashingDocs.config { |c| c.template_file = 'spec/fake_template.md.erb' } }
+      let!(:template) { SmashingDocs.config { |c| c.template_file = 'gem_rspec/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")

data/lib/base.rb

@@ -16,28 +16,27 @@ class SmashingDocs
     @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)
+  def run!(request, response, called_by_test_hook)
+    run_all = self.class::Conf.run_all
     if @skip
       @skip = false
       return
     end
-    add_test_case(request, response)
+    if run_all
+      add_test_case(request, response)
+    else
+      add_test_case(request, response) unless called_by_test_hook
+    end
     @information = {}
-    @skip = false
     self
   end
 
   def add_test_case(request, response)
-    test = self.class::TestCase.new(request, response, @information, @aside)
+    test = self.class::TestCase.new(request, response, @information)
     test.template = self.class::Conf.template
     self.tests << test
   end
@@ -67,13 +66,15 @@ class SmashingDocs
 # for an instance variable to be declared and used
 
   def self.finish!
-    current.sort_by_url!
-    current.output_testcases_to_file
-    current.clean_up!
+    unless current.tests.empty?
+      current.sort_by_url!
+      current.output_testcases_to_file
+      current.clean_up!
+    end
   end
 
-  def self.run!(request, response)
-    current.run!(request, response)
+  def self.run!(request, response, called_by_test_hook = false)
+    current.run!(request, response, called_by_test_hook)
   end
 
   def self.skip
@@ -84,10 +85,6 @@ class SmashingDocs
     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

data/lib/conf.rb

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

data/lib/generators/smashing_documentation/install_generator.rb

@@ -24,6 +24,7 @@ module SmashingDocumentation
           "SmashingDocs.config do |c|\n"\
           "  c.template_file = 'smashing_docs/template.md'\n"\
           "  c.output_file   = 'smashing_docs/api_docs.md'\n"\
+          "  c.run_all       = true\n"\
           "end"
           ) unless File.readlines(destination).grep(/SmashingDocs.config/).any?
       end
@@ -34,7 +35,7 @@ module SmashingDocumentation
           insert_into_file(
             destination,
             "\n  config.after(:each, type: :controller) do\n"\
-            "    SmashingDocs.run!(request, response)\n"\
+            "    SmashingDocs.run!(request, response, true)\n"\
             "  end\n"\
             "  config.after(:suite) { SmashingDocs.finish! }",
             after: "RSpec.configure do |config|"

data/lib/test_case.rb

@@ -1,11 +1,11 @@
 require 'erb'
 
 class SmashingDocs::TestCase
-  attr_reader :request, :response, :created_at, :information, :aside
+  attr_reader :request, :response, :created_at, :information
   attr_accessor :template
 
-  def initialize(request, response, information = {}, aside = '')
-    @request, @response, @information, @aside = request, response, information, aside
+  def initialize(request, response, information = {})
+    @request, @response, @information = request, response, information
     @created_at = Time.now
   end
 

data/smashing_docs.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |s|
   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.1.0'
+  s.version = '1.0.0'
 
   s.add_development_dependency "bundler", "~> 1.11"
   s.add_development_dependency "rake", "~> 10.0"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: smashing_docs
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Tyler Rockwell
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-02-23 00:00:00.000000000 Z
+date: 2016-02-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler