smashing_docs 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 31bc78abe84edc9c4717b1b0d1c792c23cef3cdc
-  data.tar.gz: 8f1dce8a1fd1be5e34512a7ac4c2847142d6881e
+  metadata.gz: 26647e5613a7de2ae48b1b45290021d6421c2fbc
+  data.tar.gz: d3895c49e8d1f5cc6703cc9fc3e03d599794068f
 SHA512:
-  metadata.gz: 59e40621f291e1b6af8e0cff399de36ef81c0c6ac20e2c41b00c43e6c6b6d64b47c40dab566816ae2eaa659618057a41108fcaad5ac6f60fd5ac86b4b9300778
-  data.tar.gz: 1b32b71daeba769df485cd1318da17c877f9444981956df1b7837aac5b06f83b539620a93e3a216ad176735cbe239be8794d4932609669e3ba228dcd573ec55d
+  metadata.gz: dab20613149d2467798fe72dc8fbaa72980c82514a499eed11f2bf6c079b6a79990e82b479af5d415188910ffac121937f4da5586f9a8bba7c787ef5964952a9
+  data.tar.gz: d6946b59dd25a634d646d6951d7e222affb951b2ce9fce69b90fde20aa1d09317f37b03b26419b6b27c88cace31955e13b78d62a5f7e24551721191a37eb5f0f

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    smashing_docs (0.0.2)
+    smashing_docs (1.1.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -17,8 +17,12 @@ After you bundle, run:
 `rails generate smashing_documentation:install`
 
 SmashingDocs will be configured to run on all your controller tests with the default
-template, whenever you run your tests. Your API documentation will appear in the smashing_docs
-folder in the root of your Rails app.
+template.
+
+#### To generate your docs
+
+Run `rails g smashing_documentation:build_docs`, and your docs will be waiting for you
+in the `smashing_docs` folder.
 
 ## Manual RSpec Installation
 
@@ -43,7 +47,7 @@ RSpec.configure do |config|
   config.after(:each, type: :controller) do
     SmashingDocs.run!(request, response, true)
   end
-  config.after(:suite) { SmashingDocs.finish! }
+  # config.after(:suite) { SmashingDocs.finish! }
 end
 ```
 
@@ -142,6 +146,7 @@ end
 ```
 
 #### Adding information, e.g. notes
+
 SmashingDocs will log all requests and responses by default, but you can add some
 **optional** parameters as well.
 
@@ -153,3 +158,27 @@ 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] %>`
+
+#### Auto-Push Docs to Your Project Wiki
+
+SmashingDocs can automatically push your generated docs to your project wiki.
+
+**To enable this feature**
+  1. Clone your wiki repo from Github into the same parent folder as your app
+
+  Your folder structure should be
+
+    ../projects/my_rails_app
+
+    ../projects/my_rails_app.wiki
+
+  2. Set auto_push to true in `spec_helper.rb` or `test_helper.rb`
+
+    ``` ruby
+      SmashingDocs.config do |c|
+        # configs
+        c.auto_push = true
+      end
+    ```
+
+  3. Build your docs with `rails g smashing_documentation:build_docs`

data/gem_rspec/base_spec.rb

@@ -115,4 +115,59 @@ RSpec.describe SmashingDocs do
       expect(tests.first.compile_template).to include("Endpoint note")
     end
   end
+
+  describe "#app_name" do
+    it "returns the name of the app it is installed in" do
+      expect(SmashingDocs.current.send(:app_name)).to eq("smashing_docs")
+    end
+  end
+
+  describe "#output_file" do
+    it "returns only the file name of the configured output file" do
+      expect(SmashingDocs.current.send(:output_file)).to eq("fake_output.md")
+    end
+  end
+
+  describe "#wiki_repo_exists(wiki_repo)" do
+    context "when the repo exists" do
+      let(:wiki_repo) { "../#{SmashingDocs.current.send(:app_name)}.wiki" }
+      it "returns true" do
+        expect(SmashingDocs.current.send(:wiki_repo_exists?, wiki_repo)).to eq(true)
+      end
+    end
+
+    context "when the repo does not exist" do
+      let(:wiki_repo) { "../ifyoumakethisdirectorythetestwillfail.wiki" }
+      it "returns false" do
+        expect(SmashingDocs.current.send(:wiki_repo_exists?, wiki_repo)).to eq(false)
+      end
+    end
+  end
+
+  describe "#copy_docs_to_wiki_repo(wiki_repo)" do
+    let(:wiki_repo) { "../#{SmashingDocs.current.send(:app_name)}.wiki" }
+    let(:output_file) { SmashingDocs.current.send(:output_file) }
+    it "makes a copy of the docs in the wiki folder" do
+      `rm -f ../smashing_docs.wiki/"#{output_file}"` # -f just in case the file's stubborn
+      expect(!File.exist?("../smashing_docs.wiki/#{output_file}"))
+      SmashingDocs.current.send(:copy_docs_to_wiki_repo, wiki_repo)
+      expect(File.exist?("../smashing_docs.wiki/#{output_file}"))
+    end
+  end
+
+  describe "#auto_push?" do
+    context "when auto_push configuration is false" do
+      let!(:config) { SmashingDocs.config { |c| c.auto_push = false } }
+      it "returns false" do
+        expect(!SmashingDocs.current.send(:auto_push?))
+      end
+    end
+    context "when auto_push configuration is true" do
+      let!(:config) { SmashingDocs.config { |c| c.auto_push = true } }
+      it "returns true" do
+        expect(SmashingDocs.current.send(:auto_push?))
+        SmashingDocs.config { |c| c.auto_push = false } # Config stays changed without this line
+      end
+    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.auto_push     = false
       c.run_all       = true
     end
   }
@@ -19,4 +20,8 @@ RSpec.describe SmashingDocs::Conf do
   it "sets run_all" do
     expect(SmashingDocs::Conf.run_all).to eq(true)
   end
+
+  it "sets the auto_push boolean" do
+    expect(!SmashingDocs::Conf.auto_push)
+  end
 end

data/gem_rspec/install_generator_spec.rb

@@ -30,13 +30,13 @@ RSpec.describe SmashingDocumentation::Generators::InstallGenerator, type: :gener
       end
     end
   end
-  
   context "when rspec is not installed" do
     it "does not install smashing_docs" do
+      `rm -f "#{rails_helper}"`
       File.rename('spec', 's') if Dir.exists?('spec')
       run_generator
-      expect(File).to_not exist(rails_helper)
       File.rename('s', 'spec') if Dir.exists?('s')
+      expect(File).to_not exist(rails_helper)
 
       # STDOUT is not tested here because it is suppressed in generator tests
     end

data/gem_rspec/spec_helper.rb

@@ -1,6 +1,5 @@
 $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

data/lib/base.rb

@@ -16,6 +16,17 @@ class SmashingDocs
     @tests = []
   end
 
+  def add_docs_to_wiki
+    wiki_repo = "../#{app_name}.wiki"
+    if wiki_repo && wiki_repo_exists?(wiki_repo)
+      copy_docs_to_wiki_repo(wiki_repo)
+      push_docs_to_github(wiki_repo)
+    else
+      puts "Wiki folder was not found. Please set up and clone your"\
+           " wiki before using auto push"
+    end
+  end
+
   def information(key, value)
     @information[key] = value
   end
@@ -60,6 +71,10 @@ class SmashingDocs
     end
   end
 
+  def auto_push?
+    self.class::Conf.auto_push
+  end
+
 # = = = =
 # These class methods are used to persist test data across tests
 # RSpec and Minitest do not support hooks that would allow
@@ -69,6 +84,7 @@ class SmashingDocs
     unless current.tests.empty?
       current.sort_by_url!
       current.output_testcases_to_file
+      current.add_docs_to_wiki if current.auto_push?
       current.clean_up!
     end
   end
@@ -94,3 +110,30 @@ class SmashingDocs
     yield(self::Conf)
   end
 end
+# = = = =
+private
+
+def app_name
+  directory = `pwd`
+  directory.match(/\w+\n/).to_s.gsub(/\n/, "")
+end
+
+def output_file
+  SmashingDocs::Conf.output_file.match(/\w+\.md/).to_s
+end
+
+def wiki_repo_exists?(wiki_repo)
+  File.exist?(wiki_repo)
+end
+
+def copy_docs_to_wiki_repo(wiki_repo)
+  `cp "#{SmashingDocs::Conf.output_file}" "#{wiki_repo}"`
+end
+
+def push_docs_to_github(wiki_repo)
+  Dir.chdir(wiki_repo) do
+    `git add "#{output_file}"`
+    `git commit -m "Update Docs -- Auto post by SmashingDocs"`
+    `git push`
+  end
+end

data/lib/conf.rb

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

data/lib/generators/smashing_documentation/build_docs_generator.rb

@@ -0,0 +1,18 @@
+require 'rails/generators'
+module SmashingDocumentation
+  module Generators
+    class BuildDocsGenerator < Rails::Generators::Base
+      source_root File.expand_path("../../../templates/", __FILE__)
+      def build_docs
+        destination = "spec/spec_helper.rb"
+        if File.exist?(destination)
+          uncomment_lines(destination, /config.after\(:suite\) \{ SmashingDocs.finish! \}/)
+          `rspec spec`
+          comment_lines(destination, /config.after\(:suite\) \{ SmashingDocs.finish! \}/)
+        else
+          puts "Could not find spec/spec_helper.rb"
+        end
+      end
+    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.auto_push     = false\n"\
           "  c.run_all       = true\n"\
           "end"
           ) unless File.readlines(destination).grep(/SmashingDocs.config/).any?
@@ -37,7 +38,7 @@ module SmashingDocumentation
             "\n  config.after(:each, type: :controller) do\n"\
             "    SmashingDocs.run!(request, response, true)\n"\
             "  end\n"\
-            "  config.after(:suite) { SmashingDocs.finish! }",
+            " # config.after(:suite) { SmashingDocs.finish! }",
             after: "RSpec.configure do |config|"
           ) unless File.readlines(destination).grep(/SmashingDocs.finish/).any?
         end

data/lib/templates/real_template.md

@@ -1,16 +1,45 @@
+## <%= information[:endpoint_title] || ' ' %>
+
 #### <%= request.method %> <%= request.path %>
 
-<%= information[:note] %>
+<%= information[:about] %>
 
-| Param | Value |
-| ----- | ----- |
-<%= table_entries = []
-  request.params.except(:controller, :action, :format).each do |param, value|
+### Query Parameters
+| Parameter | Value |
+| --------- | ----- |
+<%=
+  table_entries = []
+  request_params = request.params.except(:controller, :action, :format)
+  request_params.each do |param, value|
     table_entries << "| #{param} | #{value} |"
   end
-  table_entries.join("\n") %>
 
-Response: <%= response.status %>
+  table_entries << "| none | nil |" if table_entries.empty?
+  table_entries.join("\n")
+%>
+
+### Response
+**Status: <%= response.status %>**
+
+**Response Headers**
+
+| Field | Value |
+| ----- | ----- |
+<%=
+table_entries = []
+response.headers.each do |header, value|
+  table_entries << "| #{header} | #{value} |"
+end
+
+table_entries << "| none | nil |" if table_entries.empty?
+table_entries.join("\n")
+%>
+
+**JSON Example**
 ```json
 <%= JSON.pretty_generate(JSON.parse(response.body)) %>
 ```
+
+<%= information[:note] %>
+
+=================================================================================

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 = '1.0.0'
+  s.version = '1.1.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: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Tyler Rockwell
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-02-24 00:00:00.000000000 Z
+date: 2016-02-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -91,6 +91,7 @@ files:
 - gem_rspec/test_case_spec.rb
 - lib/base.rb
 - lib/conf.rb
+- lib/generators/smashing_documentation/build_docs_generator.rb
 - lib/generators/smashing_documentation/install_generator.rb
 - lib/smashing_docs.rb
 - lib/templates/real_template.md