rack-usermanual 0.1.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    YTU5Mzg1NWM1NzFkMzA5Y2RiMDc2OWNhYjBlMzRjZjNjNmM1YzU0MQ==
+  data.tar.gz: !binary |-
+    MDE4NDA4NzI1MTcxNDM1Y2IxMTc0NmM2NTYwYjNkZjdkOTgyMTZhZA==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    MjVmNDQ2ZmJmNDFlMGQ4NmVlYmRiZWUwYWY5MzA0N2IyNzhkYmYwNzU2OGU4
+    MTRhYzBlZDVlYTMwODIwMWUyYzVjYTBlMTBiNjBiYTY2YjYzMWJjOTQ1OWM0
+    YTI3MDA3ZTc3MjAxYmU2OTkyY2VlYjZlM2ZiY2ZmMDRhYTExM2I=
+  data.tar.gz: !binary |-
+    ZWI2MTI3NDBhODVkM2FiY2E0YjAwMDBjYTU3MDJiYmYzZTU3MzA0OThlN2Iz
+    Y2YyOTQ4ZWMxN2I5ZjliNDlkMzBhNmI0MDQ1YzlkYWE5YmNiNzkxYWNkNmEy
+    OGYwZmFjZjdlOTc3MjBjNWRjYmViMzg5N2IxMWNhYTBhZmFkYWY=

data/.gitignore

@@ -0,0 +1 @@
+Gemfile.lock

data/.rspec

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

data/Gemfile

@@ -0,0 +1,3 @@
+source "http://rubygems.org"
+
+gemspec

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2013 Chris Parsons
+
+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,39 @@
+Rack::Usermanual
+================
+
+This little piece of middleware helps you expose your cucumber features in a readable 'manual-like' style for your users to consume.
+
+To use, add the following to your Rack app:
+
+```
+# Choose whatever url endpoint you like.
+map "/help" do
+  use Rack::Usermanual,
+    # `sections`: Sections of the manual: human readable name together
+    # with a path to a folder containing the features.
+    :sections => {
+      "Game manual" => 'features/docs/game-manual',
+      "API documentation" => 'features/docs/api-documentation'
+    },
+    # `index`: Markdown to display on the index page of the help.
+    :index => 'features/docs/README.md',
+    # `views`: Look in here for the layout: layout.erb, layout.haml etc.
+    :views => File.join(Dir.pwd, 'views')
+end
+```
+
+Then start your app and point your browser to `/help` and your features should be displayed for you!
+
+The app will use the layout that you have in layout.{erb,haml} in whichever folder you specify. The CSS in the views is based on bootstrap: you might need to style your features slightly differently to get them to work in the way that you want. In the future it may be possible to completely override the views with your own.
+
+## Contributing
+
+We work on pull requests. If you have an idea for something you'd like to contribute, here's how to do it:
+
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.

data/lib/rack/usermanual/app.rb

@@ -0,0 +1,73 @@
+require 'gherkin'
+require 'gherkin/formatter/json_formatter'
+require 'stringio'
+require 'json'
+require 'sinatra'
+require 'kramdown'
+
+module Rack
+  class Usermanual < Sinatra::Base
+    VERSION = "0.1.0"
+
+    def initialize(app, options)
+      super(app)
+      @sections = options[:sections]
+      @index = options[:index]
+      @main_views = options[:views]
+    end
+
+    helpers do
+      def find_template(views, name, engine, &block)
+        new_views = [
+          ::File.expand_path(::File.join(::File.dirname(__FILE__), '..', '..', '..', 'views')),
+          @main_views
+        ].flatten.compact
+        Array(new_views).each { |v| super(v, name, engine, &block) }
+      end
+
+      def h(text)
+        Rack::Utils.escape_html(text)
+      end
+
+      def replace_start(sentence)
+        {
+          /^given / => 'Assume ',
+          /^but / => 'However, ',
+          /^and / => ''
+        }.each do |find, replace|
+          sentence.sub!(find, replace)
+        end
+        sentence
+      end
+    end
+
+    get '/?' do
+      haml :index
+    end
+
+    def get_feature(path, page)
+      sio = StringIO.new
+      json_formatter = Gherkin::Formatter::JSONFormatter.new(sio)
+      parser = Gherkin::Parser::Parser.new(json_formatter)
+      raw = ::File.read("#{path}/#{page}.feature")
+      parser.parse(raw, uri, 0)
+      json_formatter.done
+      [raw, JSON.parse(sio.string)]
+    end
+
+    get %r{/([\w-]+)/([\w-]+)/?$} do
+      section_uri, @page = params[:captures]
+
+      section = @sections.select do |human_name, path|
+        ::File.basename(path) == section_uri
+      end
+      halt 404 unless section
+      @human_name = section.keys.first
+      path = section.values.first
+
+      @raw, @json = get_feature(path, @page)
+
+      haml :page
+    end
+  end
+end

data/lib/rack/usermanual.rb

@@ -0,0 +1 @@
+require 'rack/usermanual/app'

data/lib/rack-usermanual.rb

@@ -0,0 +1 @@
+require 'rack/usermanual'

data/rack-usermanual.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "rack/usermanual"
+
+Gem::Specification.new do |s|
+  s.name        = "rack-usermanual"
+  s.version     = Rack::Usermanual::VERSION
+  s.authors     = ["Chris Parsons"]
+  s.email       = ["chris.p@rsons.org"]
+  s.homepage    = "http://github.com/chrismdp/rack-usermanual"
+  s.summary     = %q{Rack endpoint to serve your cucumber features as a user manual}
+  s.description = %q{}
+
+  s.rubyforge_project = "rack-usermanual"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {spec,features}/*`.split("\n")
+  s.require_paths = ['lib']
+
+  s.add_dependency 'sinatra'
+  s.add_dependency 'haml'
+  s.add_dependency 'kramdown'
+  s.add_dependency 'gherkin'
+  s.add_dependency 'rack'
+  s.add_development_dependency 'rspec'
+  s.add_development_dependency 'rack-test'
+end

data/spec/fixtures/features/my-section/test.feature

@@ -0,0 +1,8 @@
+Feature: test feature
+  This is the preamble
+
+  Scenario: First
+    Given something is true
+    When this happens
+    Then that happens
+

data/spec/spec_helper.rb

@@ -0,0 +1,7 @@
+require 'sinatra'
+
+Sinatra::Application.environment = :test
+Bundler.require :default, :test
+
+require_relative '../lib/rack-usermanual'
+

data/spec/usermanual_spec.rb

@@ -0,0 +1,39 @@
+require 'spec_helper'
+require 'rack/test'
+
+describe Rack::Usermanual do
+  include Rack::Test::Methods
+
+  def app
+    Rack::Usermanual.new(nil, :sections => {'My section' => 'spec/fixtures/features/my-section'})
+  end
+
+  it "grabs a file from the features folder" do
+    get '/help/my-section/test'
+    last_response.should be_ok
+    last_response.body.should include("This is the preamble")
+  end
+
+  it "accepts trailing slashes" do
+    get '/help/my-section/test/'
+    last_response.should be_ok
+    last_response.body.should include("This is the preamble")
+  end
+
+  it "formats that file correctly" do
+    get '/help/my-section/test'
+    last_response.body.should include("Assume something is true")
+  end
+
+  it "does not allow you to get a random filesystem file" do
+    get '/help/../../lib/solweb.rb'
+    last_response.should_not be_ok
+    get '/help/../docs/game-manual/combat.feature'
+    last_response.should_not be_ok
+  end
+
+  it "returns 404 if the file doesn't exist" do
+    get '/help/game-manual/cimbat'
+    last_response.should_not be_ok
+  end
+end

data/views/_menu.haml

@@ -0,0 +1,10 @@
+%nav.span3.pull-right
+  %ul.nav.nav-list.affix-top{:'data-offset-top' => 100, :'data-spy' => 'affix'}
+    - @sections.each do |human_name, path|
+      %li.nav-header= human_name
+      - if (features = Dir.glob(path + '/*.feature').sort).empty?
+        %small.muted No docs yet.
+      - features.each do |fn|
+        - name = ::File.basename(fn, '.feature')
+        %li
+          %a{:href => "/help/#{::File.basename(path)}/#{name}"}= name.capitalize.gsub(/[-_]/, ' ')

data/views/_pending.haml

@@ -0,0 +1,4 @@
+- if element['tags'] && element['tags'].any? {|t| t['name'] == '@pending' }
+  .alert.alert-info
+    %strong Please note:
+    This #{element['keyword'].downcase} does not yet exist, but is planned for some point in the future.

data/views/index.haml

@@ -0,0 +1,7 @@
+%h4.page-header Help & support
+
+.container
+  .row
+    = haml :_menu
+    %article.span9
+      = ::Kramdown::Document.new(h(::File.read(@index))).to_html

data/views/page.haml

@@ -0,0 +1,45 @@
+%h4.page-header
+  %a{:href => '/help'} Help & support
+  == » #{@human_name} » #{@page.capitalize}
+
+.container
+  .row
+    = haml :_menu
+    %article.span9.help-text
+      %h1= @json.first['name']
+      = haml :_pending, :locals => { :element => @json.first }
+      = ::Kramdown::Document.new(h(@json.first['description'])).to_html
+
+      - elements = @json.first['elements']
+      - if elements
+        %h4 Some examples:
+        .examples
+          - elements = @json.first['elements']
+          - if elements.first['keyword'] == 'Background'
+            .well.well-small
+              %strong Note:
+              The following examples assume
+              = elements.first['steps'].map{|s| 'that ' + s['name']}.to_sentence + '.'
+          - elements.select { |e| e['keyword'] == 'Scenario' }.each do |example|
+            %h5.example== Example: #{example['name'].downcase}
+            = haml :_pending, :locals => { :element => example }
+            %p
+              %em
+                - if example['steps']
+                  - example['steps'].slice_before {|step| step['keyword'] =~ /When|But/ }.each do |chunk|
+                    = replace_start(chunk.map { |step| step['keyword'].downcase + step['name'] }.join(', ')).tap {|s| s.sub!(/./, &:upcase) } + '.'
+                - else
+                  %span.muted This example hasn't yet been detailed.
+      %hr
+      %footer.muted
+        %small
+          Generated automatically from this project's
+          %a{:href => "http://github.com/cucumber/cucumber"} Cucumber
+          features.
+          View the
+          %a{:href => 'javascript:false', :'data-toggle' => 'collapse', :'data-target' => '#source'} source.
+        %br
+        %br
+        #source.collapse
+          %pre
+            %code= @raw

metadata

@@ -0,0 +1,161 @@
+--- !ruby/object:Gem::Specification
+name: rack-usermanual
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Chris Parsons
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-06-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sinatra
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: haml
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: kramdown
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: gherkin
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: ''
+email:
+- chris.p@rsons.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- Gemfile
+- LICENSE
+- README.md
+- lib/rack-usermanual.rb
+- lib/rack/usermanual.rb
+- lib/rack/usermanual/app.rb
+- rack-usermanual.gemspec
+- spec/fixtures/features/my-section/test.feature
+- spec/spec_helper.rb
+- spec/usermanual_spec.rb
+- views/_menu.haml
+- views/_pending.haml
+- views/index.haml
+- views/page.haml
+homepage: http://github.com/chrismdp/rack-usermanual
+licenses: []
+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: rack-usermanual
+rubygems_version: 2.0.3
+signing_key: 
+specification_version: 4
+summary: Rack endpoint to serve your cucumber features as a user manual
+test_files:
+- spec/fixtures/features/my-section/test.feature
+- spec/spec_helper.rb
+- spec/usermanual_spec.rb
+has_rdoc: