doculab 0.1.0

data/doculab.gemspec

@@ -0,0 +1,145 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{doculab}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Michael Klett"]
+  s.date = %q{2010-08-18}
+  s.description = %q{A Rails Engine for a simple file-based CMS, suitable for a documentation site.  Originally created to power the Chargify documentation at http://docs.chargify.com}
+  s.email = %q{michael@webadvocate.com}
+  s.extra_rdoc_files = [
+    "README.rdoc"
+  ]
+  s.files = [
+    ".gitignore",
+     "Gemfile",
+     "Gemfile.lock",
+     "MIT-LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "app/controllers/doculab/docs_controller.rb",
+     "app/helpers/doculab/docs_helper.rb",
+     "app/helpers/doculab/table_of_contents_helper.rb",
+     "app/models/doculab/doc.rb",
+     "app/models/doculab/table_of_contents.rb",
+     "app/sweepers/doculab/cache_sweeper.rb",
+     "config/cucumber.yml",
+     "config/rails_template.rb",
+     "config/routes.rb",
+     "doculab.gemspec",
+     "features/step_definitions/doc_steps.rb",
+     "features/step_definitions/web_steps.rb",
+     "features/support/env.rb",
+     "features/support/paths.rb",
+     "features/viewing_docs.feature",
+     "lib/doculab.rb",
+     "lib/doculab/engine.rb",
+     "lib/tasks/doculab.rake",
+     "spec/controllers/docs_controller_spec.rb",
+     "spec/dummy/Rakefile",
+     "spec/dummy/app/controllers/application_controller.rb",
+     "spec/dummy/app/helpers/application_helper.rb",
+     "spec/dummy/app/views/layouts/application.html.erb",
+     "spec/dummy/config.ru",
+     "spec/dummy/config/application.rb",
+     "spec/dummy/config/boot.rb",
+     "spec/dummy/config/database.yml",
+     "spec/dummy/config/environment.rb",
+     "spec/dummy/config/environments/development.rb",
+     "spec/dummy/config/environments/production.rb",
+     "spec/dummy/config/environments/test.rb",
+     "spec/dummy/config/initializers/backtrace_silencers.rb",
+     "spec/dummy/config/initializers/doculab.rb",
+     "spec/dummy/config/initializers/inflections.rb",
+     "spec/dummy/config/initializers/mime_types.rb",
+     "spec/dummy/config/initializers/secret_token.rb",
+     "spec/dummy/config/initializers/session_store.rb",
+     "spec/dummy/config/locales/en.yml",
+     "spec/dummy/config/routes.rb",
+     "spec/dummy/doculab/docs/overview.textile",
+     "spec/dummy/doculab/layouts/custom.html.erb",
+     "spec/dummy/doculab/layouts/docs.html.erb",
+     "spec/dummy/public/404.html",
+     "spec/dummy/public/422.html",
+     "spec/dummy/public/500.html",
+     "spec/dummy/public/favicon.ico",
+     "spec/dummy/public/javascripts/application.js",
+     "spec/dummy/public/javascripts/controls.js",
+     "spec/dummy/public/javascripts/dragdrop.js",
+     "spec/dummy/public/javascripts/effects.js",
+     "spec/dummy/public/javascripts/prototype.js",
+     "spec/dummy/public/javascripts/rails.js",
+     "spec/dummy/public/stylesheets/.gitkeep",
+     "spec/dummy/script/rails",
+     "spec/integration/navigation_spec.rb",
+     "spec/models/doc_spec.rb",
+     "spec/spec_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/grasshopperlabs/doculab}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{A Rails Engine for creating a simple documentation site}
+  s.test_files = [
+    "spec/controllers/docs_controller_spec.rb",
+     "spec/dummy/app/controllers/application_controller.rb",
+     "spec/dummy/app/helpers/application_helper.rb",
+     "spec/dummy/config/application.rb",
+     "spec/dummy/config/boot.rb",
+     "spec/dummy/config/environment.rb",
+     "spec/dummy/config/environments/development.rb",
+     "spec/dummy/config/environments/production.rb",
+     "spec/dummy/config/environments/test.rb",
+     "spec/dummy/config/initializers/backtrace_silencers.rb",
+     "spec/dummy/config/initializers/doculab.rb",
+     "spec/dummy/config/initializers/inflections.rb",
+     "spec/dummy/config/initializers/mime_types.rb",
+     "spec/dummy/config/initializers/secret_token.rb",
+     "spec/dummy/config/initializers/session_store.rb",
+     "spec/dummy/config/routes.rb",
+     "spec/integration/navigation_spec.rb",
+     "spec/models/doc_spec.rb",
+     "spec/spec_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<tilt>, [">= 0"])
+      s.add_runtime_dependency(%q<RedCloth>, [">= 0"])
+      s.add_development_dependency(%q<rails>, [">= 3.0.0.rc"])
+      s.add_development_dependency(%q<rspec-rails>, [">= 2.0.0.beta"])
+      s.add_development_dependency(%q<jeweler>, [">= 0"])
+      s.add_development_dependency(%q<cucumber>, [">= 0"])
+      s.add_development_dependency(%q<cucumber-rails>, [">= 0"])
+      s.add_development_dependency(%q<capybara>, [">= 0"])
+    else
+      s.add_dependency(%q<tilt>, [">= 0"])
+      s.add_dependency(%q<RedCloth>, [">= 0"])
+      s.add_dependency(%q<rails>, [">= 3.0.0.rc"])
+      s.add_dependency(%q<rspec-rails>, [">= 2.0.0.beta"])
+      s.add_dependency(%q<jeweler>, [">= 0"])
+      s.add_dependency(%q<cucumber>, [">= 0"])
+      s.add_dependency(%q<cucumber-rails>, [">= 0"])
+      s.add_dependency(%q<capybara>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<tilt>, [">= 0"])
+    s.add_dependency(%q<RedCloth>, [">= 0"])
+    s.add_dependency(%q<rails>, [">= 3.0.0.rc"])
+    s.add_dependency(%q<rspec-rails>, [">= 2.0.0.beta"])
+    s.add_dependency(%q<jeweler>, [">= 0"])
+    s.add_dependency(%q<cucumber>, [">= 0"])
+    s.add_dependency(%q<cucumber-rails>, [">= 0"])
+    s.add_dependency(%q<capybara>, [">= 0"])
+  end
+end
+

data/features/step_definitions/doc_steps.rb

@@ -0,0 +1,16 @@
+Given /^there is a valid doc file$/ do
+  if filename = first_existing_doc_filename
+    permalink = filename.split(".").first
+  else
+    permalink = nil
+  end
+  @doc = Doculab::Doc.find(permalink)
+end
+
+Then /^I should see the doc content$/ do
+  Then %{I should see "#{@doc.content}"}
+end
+
+def first_existing_doc_filename
+  Doculab::Doc.filenames.first
+end

data/features/step_definitions/web_steps.rb

@@ -0,0 +1,219 @@
+# IMPORTANT: This file is generated by cucumber-rails - edit at your own peril.
+# It is recommended to regenerate this file in the future when you upgrade to a 
+# newer version of cucumber-rails. Consider adding your own code to a new file 
+# instead of editing this one. Cucumber will automatically load all features/**/*.rb
+# files.
+
+
+require 'uri'
+require 'cgi'
+require File.expand_path(File.join(File.dirname(__FILE__), "..", "support", "paths"))
+
+module WithinHelpers
+  def with_scope(locator)
+    locator ? within(locator) { yield } : yield
+  end
+end
+World(WithinHelpers)
+
+Given /^(?:|I )am on (.+)$/ do |page_name|
+  visit path_to(page_name)
+end
+
+When /^(?:|I )go to (.+)$/ do |page_name|
+  visit path_to(page_name)
+end
+
+When /^(?:|I )press "([^"]*)"(?: within "([^"]*)")?$/ do |button, selector|
+  with_scope(selector) do
+    click_button(button)
+  end
+end
+
+When /^(?:|I )follow "([^"]*)"(?: within "([^"]*)")?$/ do |link, selector|
+  with_scope(selector) do
+    click_link(link)
+  end
+end
+
+When /^(?:|I )fill in "([^"]*)" with "([^"]*)"(?: within "([^"]*)")?$/ do |field, value, selector|
+  with_scope(selector) do
+    fill_in(field, :with => value)
+  end
+end
+
+When /^(?:|I )fill in "([^"]*)" for "([^"]*)"(?: within "([^"]*)")?$/ do |value, field, selector|
+  with_scope(selector) do
+    fill_in(field, :with => value)
+  end
+end
+
+# Use this to fill in an entire form with data from a table. Example:
+#
+#   When I fill in the following:
+#     | Account Number | 5002       |
+#     | Expiry date    | 2009-11-01 |
+#     | Note           | Nice guy   |
+#     | Wants Email?   |            |
+#
+# TODO: Add support for checkbox, select og option
+# based on naming conventions.
+#
+When /^(?:|I )fill in the following(?: within "([^"]*)")?:$/ do |selector, fields|
+  with_scope(selector) do
+    fields.rows_hash.each do |name, value|
+      When %{I fill in "#{name}" with "#{value}"}
+    end
+  end
+end
+
+When /^(?:|I )select "([^"]*)" from "([^"]*)"(?: within "([^"]*)")?$/ do |value, field, selector|
+  with_scope(selector) do
+    select(value, :from => field)
+  end
+end
+
+When /^(?:|I )check "([^"]*)"(?: within "([^"]*)")?$/ do |field, selector|
+  with_scope(selector) do
+    check(field)
+  end
+end
+
+When /^(?:|I )uncheck "([^"]*)"(?: within "([^"]*)")?$/ do |field, selector|
+  with_scope(selector) do
+    uncheck(field)
+  end
+end
+
+When /^(?:|I )choose "([^"]*)"(?: within "([^"]*)")?$/ do |field, selector|
+  with_scope(selector) do
+    choose(field)
+  end
+end
+
+When /^(?:|I )attach the file "([^"]*)" to "([^"]*)"(?: within "([^"]*)")?$/ do |path, field, selector|
+  with_scope(selector) do
+    attach_file(field, path)
+  end
+end
+
+Then /^(?:|I )should see JSON:$/ do |expected_json|
+  require 'json'
+  expected = JSON.pretty_generate(JSON.parse(expected_json))
+  actual   = JSON.pretty_generate(JSON.parse(response.body))
+  expected.should == actual
+end
+
+Then /^(?:|I )should see "([^"]*)"(?: within "([^"]*)")?$/ do |text, selector|
+  with_scope(selector) do
+    if page.respond_to? :should
+      page.should have_content(text)
+    else
+      assert page.has_content?(text)
+    end
+  end
+end
+
+Then /^(?:|I )should see \/([^\/]*)\/(?: within "([^"]*)")?$/ do |regexp, selector|
+  regexp = Regexp.new(regexp)
+  with_scope(selector) do
+    if page.respond_to? :should
+      page.should have_xpath('//*', :text => regexp)
+    else
+      assert page.has_xpath?('//*', :text => regexp)
+    end
+  end
+end
+
+Then /^(?:|I )should not see "([^"]*)"(?: within "([^"]*)")?$/ do |text, selector|
+  with_scope(selector) do
+    if page.respond_to? :should
+      page.should have_no_content(text)
+    else
+      assert page.has_no_content?(text)
+    end
+  end
+end
+
+Then /^(?:|I )should not see \/([^\/]*)\/(?: within "([^"]*)")?$/ do |regexp, selector|
+  regexp = Regexp.new(regexp)
+  with_scope(selector) do
+    if page.respond_to? :should
+      page.should have_no_xpath('//*', :text => regexp)
+    else
+      assert page.has_no_xpath?('//*', :text => regexp)
+    end
+  end
+end
+
+Then /^the "([^"]*)" field(?: within "([^"]*)")? should contain "([^"]*)"$/ do |field, selector, value|
+  with_scope(selector) do
+    field = find_field(field)
+    field_value = (field.tag_name == 'textarea') ? field.text : field.value
+    if field_value.respond_to? :should
+      field_value.should =~ /#{value}/
+    else
+      assert_match(/#{value}/, field_value)
+    end
+  end
+end
+
+Then /^the "([^"]*)" field(?: within "([^"]*)")? should not contain "([^"]*)"$/ do |field, selector, value|
+  with_scope(selector) do
+    field = find_field(field)
+    field_value = (field.tag_name == 'textarea') ? field.text : field.value
+    if field_value.respond_to? :should_not
+      field_value.should_not =~ /#{value}/
+    else
+      assert_no_match(/#{value}/, field_value)
+    end
+  end
+end
+
+Then /^the "([^"]*)" checkbox(?: within "([^"]*)")? should be checked$/ do |label, selector|
+  with_scope(selector) do
+    field_checked = find_field(label)['checked']
+    if field_checked.respond_to? :should
+      field_checked.should be_true
+    else
+      assert field_checked
+    end
+  end
+end
+
+Then /^the "([^"]*)" checkbox(?: within "([^"]*)")? should not be checked$/ do |label, selector|
+  with_scope(selector) do
+    field_checked = find_field(label)['checked']
+    if field_checked.respond_to? :should
+      field_checked.should be_false
+    else
+      assert !field_checked
+    end
+  end
+end
+ 
+Then /^(?:|I )should be on (.+)$/ do |page_name|
+  current_path = URI.parse(current_url).path
+  if current_path.respond_to? :should
+    current_path.should == path_to(page_name)
+  else
+    assert_equal path_to(page_name), current_path
+  end
+end
+
+Then /^(?:|I )should have the following query string:$/ do |expected_pairs|
+  query = URI.parse(current_url).query
+  actual_params = query ? CGI.parse(query) : {}
+  expected_params = {}
+  expected_pairs.rows_hash.each_pair{|k,v| expected_params[k] = v.split(',')} 
+  
+  if actual_params.respond_to? :should
+    actual_params.should == expected_params
+  else
+    assert_equal expected_params, actual_params
+  end
+end
+
+Then /^show me the page$/ do
+  save_and_open_page
+end

data/features/support/env.rb

@@ -0,0 +1,34 @@
+# IMPORTANT: This file is generated by cucumber-rails - edit at your own peril.
+# It is recommended to regenerate this file in the future when you upgrade to a 
+# newer version of cucumber-rails. Consider adding your own code to a new file 
+# instead of editing this one. Cucumber will automatically load all features/**/*.rb
+# files.
+
+ENV["RAILS_ENV"] ||= "test"
+require File.expand_path(File.dirname(__FILE__) + '/../../spec/dummy/config/environment')
+
+require 'cucumber/formatter/unicode' # Remove this line if you don't want Cucumber Unicode support
+require 'cucumber/rails/rspec'
+require 'cucumber/rails/world'
+require 'cucumber/web/tableish'
+
+require 'capybara/rails'
+require 'capybara/cucumber'
+require 'capybara/session'
+require 'cucumber/rails/capybara_javascript_emulation' # Lets you click links with onclick javascript handlers without using @culerity or @javascript
+# Capybara defaults to XPath selectors rather than Webrat's default of CSS3. In
+# order to ease the transition to Capybara we set the default here. If you'd
+# prefer to use XPath just remove this line and adjust any selectors in your
+# steps to use the XPath syntax.
+Capybara.default_selector = :css
+
+# If you set this to false, any error raised from within your app will bubble 
+# up to your step definition and out to cucumber unless you catch it somewhere
+# on the way. You can make Rails rescue errors and render error pages on a
+# per-scenario basis by tagging a scenario or feature with the @allow-rescue tag.
+#
+# If you set this to true, Rails will rescue all errors and render error
+# pages, more or less in the same way your application would behave in the
+# default production environment. It's not recommended to do this for all
+# of your scenarios, as this makes it hard to discover errors in your application.
+ActionController::Base.allow_rescue = false

data/features/support/paths.rb

@@ -0,0 +1,28 @@
+module NavigationHelpers
+  # Maps a name to a path. Used by the
+  #
+  #   When /^I go to (.+)$/ do |page_name|
+  #
+  # step definition in web_steps.rb
+  #
+  def path_to(page_name)
+    case page_name
+
+    when /the home\s?page/
+      '/'
+    when /the doculab doc/
+      doculab_doc_path(@doc.permalink)
+    else
+      begin
+        page_name =~ /the (.*) page/
+        path_components = $1.split(/\s+/)
+        self.send(path_components.push('path').join('_').to_sym)
+      rescue Object => e
+        raise "Can't find mapping from \"#{page_name}\" to a path.\n" +
+          "Now, go and add a mapping in #{__FILE__}"
+      end
+    end
+  end
+end
+
+World(NavigationHelpers)

data/features/viewing_docs.feature

@@ -0,0 +1,10 @@
+Feature: Viewing document pages
+
+  In order to be enlightened
+  As a website visitor
+  I want to view document pages
+  
+  Scenario: View an existing document page written in textile
+    Given there is a valid doc file
+    When I go to the doculab doc
+    Then I should see the doc content

data/lib/doculab/engine.rb

@@ -0,0 +1,43 @@
+class Engine < Rails::Engine
+  initializer "doculab.add_view_paths", :before => :add_view_paths do |app|
+    app.config.paths.app.views << Rails.root.join("doculab").to_s
+  end
+  
+  initializer "doculab.table_of_contents_preparation", :before => :add_to_prepare_blocks do |app|
+    app.config.to_prepare do
+      table_of_contents = Engine.table_of_contents_path
+      begin
+        load table_of_contents
+      rescue LoadError
+        Doculab::TableOfContents.define do; end
+        if %w(production development).include?(Rails.env)
+          Engine.print_warning(:table_of_contents)
+        end
+      end
+    end
+  end
+  
+  initializer "doculab.sweep_cache" do |app|
+    Doculab::CacheSweeper.sweep!
+  end
+  
+  def self.table_of_contents_path
+    Rails.root.join("doculab", "meta", "table_of_contents.rb").to_s
+  end
+  
+  def self.print_warning(message_key)
+    message = case message_key
+    when :table_of_contents
+      "There is no Table of Contents defined at #{table_of_contents_path}"
+    else
+      nil
+    end
+  
+    if message.present?
+      message = "=> Doculab WARNING: #{message}"
+      puts message
+      Rails.logger.info message
+    end
+  end
+  
+end

data/lib/doculab.rb

@@ -0,0 +1,53 @@
+require 'rubygems'
+require 'bundler'
+
+Bundler.setup
+Bundler.require
+require 'doculab/engine'
+
+module Doculab
+  # What are you documenting?
+  mattr_accessor :project_name
+  
+  # Documentation title, used on the index page and in the <title> tag.
+  # Default is "#{project_name} Documentation"
+  #
+  # Set this in your configuration via:
+  # 
+  #     Doculab.title = "Super Amazing Documentation"
+  mattr_writer :title
+  def self.title
+    @@title ||= [Doculab.project_name, "Documentation"].reject(&:blank?).join(' ')
+  end
+  
+  # Normally, routes for Doculab are set up based off of "root":
+  #
+  #   http://docs.example.com/          # => Renders the index doc
+  #   http://docs.example.com/overview  # => Renders the "overview" doc
+  #
+  # Setting the route base can put Doculab routes in a "sub-directory":
+  #
+  #   Doculab.route_base = "my-docs"
+  #
+  #   http://docs.example.com/my-docs/          # => Renders the index page
+  #   http://docs.example.com/my-docs/overview  # => Renders the "overview" doc
+  mattr_accessor :route_base
+  
+  # Define the layout to use for your "main layout", as found in the doculab/layouts directory.
+  # Defaults to "docs" (which equates to docs.html.erb)
+  mattr_writer :main_layout
+  def self.main_layout
+    @@main_layout ||= 'docs'
+  end
+  
+  # You may optionally define a separate layout for the index page.  One use for this is to
+  # create a richer homepage with search boxes and cool stuff that's harder to do in
+  # index.textile.
+  #
+  # Consider making this "nested layout" as described in
+  # http://edgeguides.rubyonrails.org/layouts_and_rendering.html#using-nested-layouts
+  mattr_writer :index_layout
+  def self.index_layout
+    @@index_layout ||= main_layout
+  end
+end

data/lib/tasks/doculab.rake

@@ -0,0 +1,15 @@
+namespace :doculab do
+  desc "Bootstrap a doculab directory within your project"
+  task :bootstrap do
+    puts "Hello Bootstrap!"
+  end
+  
+  desc "Generate blank doc files for all pages defined in the Table of Contents which do not yet exist"
+  task :skeleton => :environment do
+    Doculab::TableOfContents.pages.each do |page|
+      unless File.exist?(page.filename)
+        FileUtils.touch(page.filename)
+      end
+    end
+  end
+end

data/spec/controllers/docs_controller_spec.rb

@@ -0,0 +1,62 @@
+require 'spec_helper'
+
+describe Doculab::DocsController do
+  describe "layout selection" do
+    before(:each) do
+      reset_layouts!
+    end
+    
+    after(:each) do
+      reset_layouts!
+    end
+
+    context "with the default layouts" do
+      it "uses the 'docs' layout for the index page" do
+        get :index
+        controller.send(:_layout).should == 'docs'
+      end
+      
+      it "uses the 'docs' layout for a doc page" do
+        get :show, :permalink => good_permalink
+        controller.send(:_layout).should == 'docs'
+      end
+    end
+    
+    context "with a custom main_layout" do
+      before(:each) do
+        Doculab.main_layout = 'custom'
+      end
+      
+      it "uses the 'custom' layout for the index page" do
+        get :index
+        controller.send(:_layout).should == 'custom'
+      end
+      
+      it "uses the 'custom' layout for a doc page" do
+        get :show, :permalink => good_permalink
+        controller.send(:_layout).should == 'custom'
+      end
+    end
+
+    context "with a custom index_layout" do
+      before(:each) do
+        Doculab.index_layout = 'custom'
+      end
+      
+      it "uses the 'custom' layout for the index page" do
+        get :index
+        controller.send(:_layout).should == 'custom'
+      end
+      
+      it "uses the 'docs' layout for a doc page" do
+        get :show, :permalink => good_permalink
+        controller.send(:_layout).should == 'docs'
+      end
+    end
+    
+    def reset_layouts!
+      Doculab.main_layout = nil
+      Doculab.index_layout = nil
+    end
+  end
+end

data/spec/dummy/Rakefile

@@ -0,0 +1,7 @@
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require File.expand_path('../config/application', __FILE__)
+require 'rake'
+
+Dummy::Application.load_tasks

data/spec/dummy/app/controllers/application_controller.rb

@@ -0,0 +1,3 @@
+class ApplicationController < ActionController::Base
+  protect_from_forgery
+end

data/spec/dummy/app/helpers/application_helper.rb

@@ -0,0 +1,2 @@
+module ApplicationHelper
+end

data/spec/dummy/app/views/layouts/application.html.erb

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Dummy</title>
+  <%= stylesheet_link_tag :all %>
+  <%= javascript_include_tag :defaults %>
+  <%= csrf_meta_tag %>
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>