cuke-api-docs 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: da0bfdf2234fa77fb9d57738038500c0c2bb4965
+  data.tar.gz: 450446cc4d5f5a9fdeb2a1665e6fda90e3128a3a
+SHA512:
+  metadata.gz: fee43606612a275432f209e657aa075d4befe646489ba37acff826e6c39ea6595740d754cd4b922a72772cc9e96b4f1084f56b002ecb3a264ab735f137469326
+  data.tar.gz: 445c9a130517d8242de6b01dff75745cb25675a208b4df3920e46e2fcebf1e0015c6e8a41315d57fe5a0f94724d81d81acd712b79b4577d91d1fd8eec1ea9970

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in cuke-api-docs.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Bruz Marzolf
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,43 @@
+# cuke-api-docs
+
+A Cucumber formatter that produces API documentation from Cucumber features that have follow a set of rules.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'cuke-api-docs'
+```
+
+## Usage
+
+Either specify it when you use Cucumber:
+
+```bash
+cucumber --format Cucumber::Formatter::ApiDocs
+```
+
+Or, add it to your Rakefile:
+
+```ruby
+Cucumber::Rake::Task.new(:docs) do |t|
+  t.cucumber_opts = "features --format Cucumber::Formatter::ApiDocs"
+end
+```
+
+So that you can do:
+
+```bash
+rake docs
+```
+
+Either way, it produces a file named docs.html, which is a self-contained HTML documentation file.
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/cuke-api-docs/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/cuke-api-docs.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'cuke-api-docs/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "cuke-api-docs"
+  spec.version       = CukeApiDocs::VERSION
+  spec.authors       = ["Bruz Marzolf"]
+  spec.email         = ["bruz@bruzilla.com"]
+  spec.summary       = %q{Cucumber formatter that produces HTML API documentation}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "arbre", "~> 1.0"
+  spec.add_dependency "cucumber", "~> 1.3"
+  spec.add_dependency "json", "~> 1.8"
+  spec.add_dependency "deep_merge", "~> 1.0"
+  spec.add_dependency "virtus", "~> 1.0"
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+end

data/lib/cucumber/formatter/api_docs.rb

@@ -0,0 +1,367 @@
+require 'virtus'
+require 'arbre'
+require 'json'
+require 'deep_merge/rails_compat'
+
+module Cucumber
+  module Formatter
+    class ApiDocs
+
+      VERB_ORDER = %w(GET POST PUT PATCH DELETE)
+
+      class Parameter
+        include Virtus.model
+
+        attribute :type, String
+        attribute :name, String
+        attribute :value, String
+      end
+
+      class Example
+        include Virtus.model
+
+        attribute :name, String
+        attribute :prerequisites, Array[String]
+        attribute :parameters, Array[Parameter]
+        attribute :code, Integer
+        attribute :content_type, String
+        attribute :json_response, Hash, default: {}
+      end
+
+      class Group
+        include Virtus.model
+
+        attribute :key, String
+        attribute :name, String
+
+        def self.for_tag(tag)
+          @groups ||= {}
+          @groups[tag] ||= create(tag)
+        end
+
+        def self.create(tag)
+          key = tag.gsub("@", "")
+          name = key.gsub("_", " ").capitalize
+
+          new(key: key, name: name)
+        end
+      end
+
+      class Endpoint
+        include Virtus.model
+
+        attribute :description, String
+        attribute :tag, String
+        attribute :group, String
+        attribute :verb, String
+        attribute :path, String
+        attribute :examples, Array[Example]
+        attribute :parameters, Array[Parameter]
+
+        def name
+          "#{verb} #{path}"
+        end
+
+        def sort_order
+          VERB_ORDER.index(verb) || fail("Unable to look up verb for #{name}")
+        end
+      end
+
+      def initialize(step_mother, io, options)
+        @endpoints = []
+      end
+
+      def after_features(features)
+        write_html
+      end
+
+      def before_feature(feature)
+        verb, path = feature.name.split(" ")
+        @endpoint = Endpoint.new(verb: verb, path: path)
+      end
+
+      def after_feature(feature)
+        @endpoint.parameters.uniq! { |parameter| parameter.name }
+        @endpoints << @endpoint
+      end
+
+      def before_comment(comment)
+        @endpoint.description = comment.to_sexp[1].gsub(/#\s*/, "")
+      end
+
+      def before_feature_element(feature_element)
+        @example = Example.new(name: feature_element.title)
+        @prior_keyword = nil
+      end
+
+      def after_feature_element(feature_element)
+        @endpoint.examples << @example
+      end
+
+      def before_step(step)
+        keyword = if step.keyword.strip == "And" && @prior_keyword
+          @prior_keyword
+        else
+          step.keyword.strip
+        end
+
+        case keyword
+        when "Given"
+          @example.prerequisites << step.name
+          @prior_keyword = "Given"
+        when "When"
+          if step.multiline_arg
+            step.multiline_arg.rows.each do |type, name, value|
+              @example.parameters << Parameter.new(type: type, name: name, value: value)
+              @endpoint.parameters << Parameter.new(type: type, name: name)
+            end
+          end
+
+          @prior_keyword = "When"
+        when "Then"
+          if matches = step.name.match(/the status code is (\d+)/)
+            @example.code = matches[1]
+          elsif matches = step.name.match(/Content-Type is (.*)$/)
+            @example.content_type = matches[1]
+          elsif matches = step.name.match(/the JSON response at "(.*?)" should include (keys)*:/)
+            key = matches[1]
+
+            if step.multiline_arg.respond_to? :rows
+              step.multiline_arg.rows.each do |nested_key, value|
+                add_json("#{key}/#{nested_key}", json_value(value))
+              end
+            else
+              add_json(key, JSON.parse(step.multiline_arg))
+            end
+          elsif matches = step.name.match(/the JSON response at "(.*?)" should be ([^ ]*?)$/)
+            keys = matches[1]
+            value = matches[2]
+            add_json(keys, json_value(value))
+          elsif matches = step.name.match(/the JSON response at "(.*?)" should be (variable )*"(.*?)"/)
+            keys = matches[1]
+            value = matches[3]
+            add_json(keys, value)
+          end
+
+          @prior_keyword = "Then"
+        end
+      end
+
+      def tag_name(tag)
+        @endpoint.group = Group.for_tag(tag)
+      end
+
+      private
+
+      def log(message)
+        @log ||= File.open("doc-debug.log", "w")
+        @log << message + "\n"
+      end
+
+      def add_json(path, terminal_value)
+        keys = path.split("/")
+
+        return @example.json_response[path] = terminal_value if keys.size == 1
+
+        keys.each_cons(2).reduce(@example.json_response) do |current, (key_one_string, key_two)|
+          key_one = if key_one_string.match(/^\d+$/)
+            key_one_string.to_i
+          else
+            key_one_string
+          end
+
+          value = case key_two
+          when /^\d+$/
+            if current[key_one].is_a?(Array)
+              current[key_one]
+            else
+              []
+            end
+          else
+            if current[key_one].is_a?(Hash)
+              current[key_one].merge(key_two => terminal_value)
+            else
+              {key_two => terminal_value}
+            end
+          end
+
+          current[key_one] = value
+
+          value
+        end
+      end
+
+      def json_value(string)
+        JSON.parse('{"key":' + string + '}')["key"]
+      end
+
+      def write_html
+        endpoints_by_group = @endpoints.group_by(&:group).sort_by { |group, _| group.name }
+
+        html = Arbre::Context.new do
+          head do
+            link rel: "stylesheet", href: "https://maxcdn.bootstrapcdn.com/bootstrap/3.2.0/css/bootstrap.min.css"
+            link rel: "stylesheet", href: "https://maxcdn.bootstrapcdn.com/bootstrap/3.2.0/css/bootstrap-theme.min.css"
+            style do
+              "
+                .summary, .panel-heading {
+                  cursor: pointer;
+                }
+
+                nav {
+                  margin-top: 38px;
+                  min-width: 255px;
+                  top: 0;
+                  bottom: 0;
+                  padding-right: 12px;
+                  padding-bottom: 12px;
+                  overflow-y: auto;
+                }
+              ".html_safe
+            end
+            script src: "https://code.jquery.com/jquery-2.1.1.min.js"
+            script src: "https://maxcdn.bootstrapcdn.com/bootstrap/3.2.0/js/bootstrap.min.js"
+          end
+
+          body do
+            div class: "container padded" do
+              div class: "col-md-3" do
+                nav class: "hidden-sm hidden-xs affix nav" do
+                  div class: "list-group" do
+                    endpoints_by_group.each do |group, _|
+                      a group.name, href: "##{group.key}", class: "list-group-item"
+                    end
+                  end
+                end
+              end
+
+              div class: "col-md-9" do
+                endpoints_by_group.each do |group, endpoints|
+                  a name: group.key
+                  h1 group.name
+
+                  endpoints.sort_by(&:sort_order).each do |endpoint|
+                    div class: "endpoint" do
+                      div class: "summary well well-sm" do
+                        text_node endpoint.name
+                        span class: "glyphicon glyphicon-plus pull-right"
+                      end
+
+                      div class: "detail panel panel-default", style: "display:none" do
+                        div class: "panel-heading" do
+                          h2 do
+                            text_node endpoint.name
+                            span class: "glyphicon glyphicon-minus pull-right"
+                          end
+                        end
+
+                        div class: "panel-body" do
+                          div endpoint.description
+
+                          h3 "Parameters"
+
+                          table class: "table table-striped table-bordered" do
+                            thead do
+                              tr do
+                                th { "Name" }
+                                th { "Type" }
+                              end
+                            end
+
+                            tbody do
+                              endpoint.parameters.each do |parameter|
+                                tr do
+                                  td { parameter.type }
+                                  td { parameter.name }
+                                end
+                              end
+                            end
+                          end
+
+                          h3 "Examples"
+                          endpoint.examples.each do |example|
+                            panel_type = case example.code
+                            when 200..299
+                              "success"
+                            when 400..499
+                              "warning"
+                            when 500.599
+                              "error"
+                            end
+
+                            div class: "panel panel-#{panel_type}" do
+                              div example.name, class: "panel-heading"
+
+                              div class: "panel-body" do
+                                h4 "Request parameters"
+                                table class: "table table-striped table-bordered" do
+                                  thead do
+                                    tr do
+                                      th { "Name" }
+                                      th { "Type" }
+                                      th { "Value" }
+                                    end
+                                  end
+
+                                  tbody do
+                                    example.parameters.each do |parameter|
+                                      tr do
+                                        td { parameter.type }
+                                        td { parameter.name }
+                                        td { parameter.value }
+                                      end
+                                    end
+                                  end
+                                end
+
+                                h4 "Response"
+
+                                div class: "panel panel-default" do
+                                  div class: "panel-heading" do
+                                    div "Code: #{example.code}"
+                                    div "Content-Type: #{example.content_type}"
+                                  end
+
+                                  div class: "panel-body" do
+                                    if example.json_response.empty?
+                                      "Empty body"
+                                    else
+                                      json = JSON.pretty_generate(example.json_response)
+                                      code json.gsub("\n", "<br>").gsub(" ", "&nbsp").html_safe
+                                    end
+                                  end
+                                end
+                              end
+                            end
+                          end
+                        end
+                      end
+                    end
+                  end
+                end
+              end
+            end
+
+            script "
+              $(document).ready(function(){
+                $('.summary').click(function() {
+                  $(this).hide();
+                  $(this).closest('.endpoint').find('.detail').show();
+                });
+
+                $('.detail .panel-heading').click(function() {
+                  $(this).closest('.detail').hide();
+                  $(this).closest('.endpoint').find('.summary').show();
+                });
+              });
+            ".html_safe
+          end
+        end
+
+        file = File.open("docs.html", "w")
+        file << html.to_s
+        file.close
+      end
+    end
+  end
+end

data/lib/cuke-api-docs/version.rb

@@ -0,0 +1,3 @@
+module CukeApiDocs
+  VERSION = "0.0.1"
+end

data/lib/cuke-api-docs.rb

@@ -0,0 +1,11 @@
+require "cuke-api-docs/version"
+require "cucumber/formatter/api_docs"
+
+# Extend Cucumber's builtin formats, so that this
+# formatter can be used with --format api-docs
+require 'cucumber/cli/main'
+
+Cucumber::Cli::Options::BUILTIN_FORMATS["api-docs"] = [
+  "Cucumber::Formatter::ApiDocs",
+  "Turns specially formatted cucumber features into API documentation"
+]

metadata

@@ -0,0 +1,151 @@
+--- !ruby/object:Gem::Specification
+name: cuke-api-docs
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Bruz Marzolf
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-11-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: arbre
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: cucumber
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: deep_merge
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: virtus
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !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'
+description: 
+email:
+- bruz@bruzilla.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- cuke-api-docs.gemspec
+- lib/cucumber/formatter/api_docs.rb
+- lib/cuke-api-docs.rb
+- lib/cuke-api-docs/version.rb
+homepage: ''
+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.2
+signing_key: 
+specification_version: 4
+summary: Cucumber formatter that produces HTML API documentation
+test_files: []