guides 0.5.0 → 0.6.1

data/.gitignore

@@ -1,2 +1,6 @@
 Gemfile.lock
+tmp
 devbin
+bundle
+Guides
+*.pmdoc

data/Gemfile

@@ -1,3 +1,6 @@
 source "http://rubygems.org"
 
 gemspec
+
+gem "rspec", "~> 2.0"
+gem "faraday", "~> 0.5.0"

data/RELEASES.yml

@@ -0,0 +1,6 @@
+versions:
+  "0.6.0":
+    pkg: "https://github.com/downloads/wycats/guides/Guides-0.6.0.pkg"
+  "0.6.1":
+    pkg: "https://github.com/downloads/wycats/guides/Guides-0.6.1.pkg"
+    patch: "https://github.com/wycats/guides/raw/patches/0.6.1.diff"

data/Rakefile

@@ -0,0 +1,33 @@
+desc "Prep the release for PackageMaker"
+task :pkg do
+  system "rm -rf Guides"
+  system "mkdir -p Guides/local/guides/lib"
+
+  `git ls-files -- lib`.split("\n").each do |file|
+    system "mkdir -p #{File.dirname("Guides/local/guides/#{file}")}"
+    system "cp #{file} Guides/local/guides/#{file}"
+  end
+
+  require "rbconfig"
+
+  unless Config::CONFIG["target_cpu"] == "universal"
+    puts "Please use a universal binary copy of ruby"
+    exit 1
+  end
+
+  unless RUBY_VERSION == "1.9.2"
+    puts "Please use Ruby 1.9.2"
+    exit 1
+  end
+
+  puts "Regenerating the bundle."
+
+  system "rm -rf bundle"
+  system "bundle --standalone"
+  system "cp -R bundle Guides/local/guides/bundle"
+
+  guides = File.read("bin/guides").sub(/\A#.*/, "#!/usr/local/ruby1.9test/bin/ruby -I /usr/local/guides/bundle -r bundler/setup")
+
+  system "mkdir -p Guides/bin"
+  File.open("Guides/bin/guides", "w") { |file| file.puts guides }
+end

data/guides.gemspec

@@ -22,6 +22,7 @@ Gem::Specification.new do |s|
   s.add_dependency "rack", "~> 1.2.1"
   s.add_dependency "RedCloth", "~> 4.1.1"
   s.add_dependency "thor", "~> 0.14.6"
+  s.add_dependency "thin", "~> 1.2.7"
 
   s.files              = `git ls-files`.split("\n")
   s.test_files         = `git ls-files -- {test,spec,features}/*`.split("\n")

data/lib/guides.rb

@@ -5,13 +5,23 @@ require "guides/textile_extensions"
 require "guides/generator"
 
 module Guides
+  class Error < StandardError
+    def self.status_code(code = nil)
+      define_method(:status_code) { code }
+    end
+  end
+
+  class FormatError < Error; status_code(2) ; end
+
   class << self
     def root
       # TODO: Search for guides.yml
       File.expand_path(Dir.pwd)
     end
 
-    def meta
+    def meta(reload = false)
+      @meta = nil if reload
+
       @meta ||= begin
         if File.exist?("#{root}/guides.yml")
           YAML.load_file("#{root}/guides.yml")

data/lib/guides/cli.rb

@@ -1,21 +1,27 @@
 require "thor"
 require "guides/new"
+require "guides/preview"
+require "guides/version"
 
 module Guides
   class CLI < Thor
     ASSETS_ROOT = File.expand_path("../assets", __FILE__)
     SOURCE_ROOT = File.expand_path("../source", __FILE__)
 
+    def self.basename
+      "guides"
+    end
+
     desc "new NAME", "create a new directory of guides"
     method_option "name", :type => :string
     def new(name)
       invoke "guides:new:copy", [name, options[:name] || name]
     end
 
-    desc "generate", "generate the guides output"
+    desc "build", "build the guides output"
     method_option "only", :type => :array
     method_option "clean", :type => :boolean
-    def generate
+    def build
       FileUtils.rm_rf("#{Guides.root}/output") if options[:clean]
       require "guides/generator"
 
@@ -27,9 +33,31 @@ module Guides
       generator.generate
     end
 
+    map "-v"        => "version"
+    map "--version" => "version"
+
+    desc "version", "print the current version"
+    def version
+      shell.say "Guides #{Guides::VERSION}", :green
+    end
+
     desc "preview", "preview the guides as you work"
     def preview
+      Preview.start
+    end
+
+    desc "update", "when running from the pkg, updates the gem"
+    def update
+      Update.start
+    end
 
+    no_tasks do
+      def invoke_task(*)
+        super
+      rescue Guides::Error => e
+        shell.say e.message, :red
+        exit e.status_code
+      end
     end
   end
 end

data/lib/guides/generator.rb

@@ -85,6 +85,33 @@ module Guides
       copy_assets
     end
 
+    def generate_guide(guide, output_file)
+      return unless generate?(guide, output_file)
+
+      puts "Generating #{output_file}"
+      File.open(File.join(output_dir, output_file), 'w') do |f|
+        view = ActionView::Base.new(source_dir, :edge => edge)
+        view.extend(Helpers)
+
+        if guide =~ /\.html\.erb$/
+          # Generate the special pages like the home.
+          view.render("sections")
+          type = @edge ? "edge" : "normal"
+          result = view.render(:layout => 'layout', :file => guide, :locals => {:guide_type => type})
+        else
+          body = File.read(File.join(source_dir, guide))
+          body = set_header_section(body, view)
+          body = set_index(body, view)
+
+          result = view.render(:layout => 'layout', :text => textile(body))
+
+          warn_about_broken_links(result) if @warnings
+        end
+
+        f.write result
+      end
+    end
+
   private
     def generate_guides
       guides_to_generate.each do |guide|
@@ -114,6 +141,12 @@ module Guides
     def generate?(source_file, output_file)
       fin  = File.join(source_dir, source_file)
       fout = File.join(output_dir, output_file)
+
+      if File.exists?(fout) && File.mtime(fout) < File.mtime(File.join(Guides.root, "guides.yml"))
+        Guides.meta(true)
+        return true
+      end
+
       all || !File.exists?(fout) || File.mtime(fout) < File.mtime(fin)
     end
 
@@ -148,8 +181,15 @@ module Guides
       new_body = body.gsub(/(.*?)endprologue\./m, '').strip
       header = $1
 
-      header =~ /h2\.(.*)/
-      page_title = "#{@meta["title"]}: #{$1.strip}"
+      unless header
+        raise FormatError, "A prologue is required. Use 'endprologue.' to separate the prologue from the main body."
+      end
+
+      if header =~ /h2\.(.*)/
+        page_title = "#{@meta["title"]}: #{$1.strip}"
+      else
+        raise FormatError, "A title is required. Use the 'h2.' declaration to denote the title."
+      end
 
       header = textile(header)
 
@@ -192,8 +232,8 @@ module Guides
 
     def textile(body, lite_mode=false)
       # If the issue with notextile is fixed just remove the wrapper.
-      with_workaround_for_notextile(body) do |body|
-        t = RedCloth.new(body)
+      with_workaround_for_notextile(body) do |new_body|
+        t = RedCloth.new(new_body)
         t.hard_breaks = false
         t.lite_mode = lite_mode
         t.to_html(:notestuff, :plusplus, :code, :tip)

data/lib/guides/helpers.rb

@@ -1,19 +1,15 @@
 module Guides
   module Helpers
-    def full_index
-
-    end
-
     def clickable_index
-      guides = Guides.meta["index"]
+      all_guides = Guides.meta["index"]
 
-      total_guides = guides.inject(0) do |sum, (name, guides)|
+      total_guides = all_guides.inject(0) do |sum, (name, guides)|
         sum + guides.size
       end
 
       lgroup, rgroup, counted_guides = {}, {}, 0
 
-      guides.each do |name, guides|
+      all_guides.each do |name, guides|
         if counted_guides > (total_guides / 2.0)
           rgroup[name] = guides
         else
@@ -39,7 +35,7 @@ module Guides
     end
 
     def author(name, nick, image = 'credits_pic_blank.gif', &block)
-      image = "images/#{image}"
+      image = "images/#{image}" unless image =~ /^http/
 
       result = content_tag(:img, nil, :src => image, :class => 'left pic', :alt => name)
       result << content_tag(:h3, name)
@@ -53,3 +49,4 @@ module Guides
     end
   end
 end
+

data/lib/guides/preview.rb

@@ -0,0 +1,50 @@
+require "rack"
+
+module Guides
+  class App
+    LOCAL_ASSETS     = File.expand_path("../templates/assets", __FILE__)
+    SOURCE_ASSETS    = File.join(Guides.root, "assets")
+    SOURCE_TEMPLATES = File.join(Guides.root, "source")
+
+    def initialize
+      @local  = Rack::File.new(LOCAL_ASSETS)
+      @source = Rack::File.new(SOURCE_ASSETS)
+      @output = Rack::File.new(File.join(Guides.root, "output"))
+    end
+
+    def call(env)
+      path = env["PATH_INFO"]
+
+      case path
+      when "/"
+        env["PATH_INFO"] = "/index.html"
+        return call(env)
+      when /(.*).html/
+        name = $1
+        generator = Guides::Generator.new({})
+        source_file = Dir["#{SOURCE_TEMPLATES}/#{name}.{html.erb,textile}"].first
+
+        unless source_file
+          return [404, {"Content-Type" => "text/html"}, ["#{name} not found"]]
+        end
+
+        generator.send(:generate_guide, File.basename(source_file), "#{name}.html")
+        return @output.call(env)
+      else
+        source = @source.call(env)
+        return source if source.first == 200
+        return @local.call(env)
+      end
+    end
+  end
+
+  class Preview < Rack::Server
+    def self.start(*)
+      super :host => '0.0.0.0', :Port => 9292, :server => "thin"
+    end
+
+    def app
+      @app ||= App.new
+    end
+  end
+end

data/lib/guides/templates/assets/stylesheets/main.css

@@ -24,7 +24,7 @@ dl dt { font-weight: bold; }
 dd { margin-left: 1.5em;}
 
 pre,code { margin: 1.5em 0; overflow: auto; color: #222;}
-pre,code,tt {
+pre,code,tt,ins {
     font-size: 1em;
     font-family: "Anonymous Pro", "Inconsolata", "Menlo", "Consolas", "Bitstream Vera Sans Mono", "Courier New", monospace;
     line-height: 1.5;
@@ -384,7 +384,7 @@ div.code_container {
 	margin: 0.25em 0 1.5em 0;
 }
 
-.note tt, .info tt {border:none; background: none; padding: 0;}
+.note tt, .note ins, .info tt, .note ins {border:none; background: none; padding: 0;}
 
 #mainCol ul li {
 	list-style:none;

data/lib/guides/templates/source/layout.html.erb

@@ -48,8 +48,12 @@
 
   <div id="feature">
     <div class="wrapper">
+    <% if header_section = yield(:header_section).presence %>
+      <%= header_section %>
+    <% else %>
       <h2><%= Guides.meta["title"] %></h2>
       <p><%= Guides.meta["description"] %></p>
+    <% end %>
     </div>
   </div>
 

data/lib/guides/textile_extensions.rb

@@ -1,4 +1,4 @@
-module RedCloth
+class RedCloth::TextileDoc
   def notestuff(body)
     body.gsub!(/^(IMPORTANT|CAUTION|WARNING|NOTE|INFO)[.:](.*)$/) do |m|
       css_class = $1.downcase

data/lib/guides/version.rb

@@ -1,3 +1,3 @@
 module Guides
-  VERSION = "0.5.0"
+  VERSION = "0.6.1"
 end

data/spec/build_spec.rb

@@ -0,0 +1,45 @@
+require "spec_helper"
+
+describe "guides build" do
+  before(:all) do
+    reset_tmp
+    guides "new", "sample" and wait
+    Dir.chdir tmp.join("sample")
+    guides "build" and wait
+  end
+
+  it "generates the app" do
+    out.should =~ /Generating contribute.html.*Generating credits.html.*Generating index.html/m
+  end
+
+  it "generates assets" do
+    files = Dir["output/*"]
+
+    File.directory?("output/images").should be_true
+    File.directory?("output/javascripts").should be_true
+    File.directory?("output/stylesheets").should be_true
+    File.file?("output/javascripts/guides.js").should be_true
+    File.file?("output/stylesheets/main.css").should be_true
+    File.file?("output/stylesheets/overrides.style.css").should be_true
+  end
+
+  it "does nothing if run twice in a row" do
+    guides "build"
+    out.should be_blank
+  end
+
+  it "re-runs if run with --clean" do
+    guides "build", "--clean"
+    out.should =~ /Generating contribute.html.*Generating credits.html.*Generating index.html/m
+  end
+
+  it "creates index.html" do
+    File.read("output/index.html").should =~ /<a href="contribute.html">/
+  end
+
+  it "creates contribute.html" do
+    contribute = File.read("output/contribute.html")
+    contribute.should =~ /<h2>Contribute<\/h2>/
+  end
+end
+

data/spec/new_spec.rb

@@ -0,0 +1,18 @@
+require "spec_helper"
+
+describe "guides new" do
+  before(:each) do
+    reset_tmp
+  end
+
+  it "prints an error if new is called with no name" do
+    guides "new", :track_stderr => true
+    err.should =~ /"new" was called incorrectly/
+  end
+
+  it "generates an app if a name is given" do
+    guides "new", "sample"
+    out.should =~ /create.*guides\.yml/
+    tmp.join("sample", "guides.yml").read.should =~ /\Atitle: sample/
+  end
+end

data/spec/preview_spec.rb

@@ -0,0 +1,35 @@
+require "spec_helper"
+
+describe "guides generate" do
+  before(:all) do
+    reset_tmp
+    guides "new", "sample" and wait
+    Dir.chdir tmp.join("sample")
+    guides "build" and wait
+  end
+
+  after(:all) do
+    Dir.chdir(tmp)
+  end
+
+  before(:each) do
+    host! :preview
+    launch_test_server
+    guides "preview"
+  end
+
+  it "downloads the index at /" do
+    get "/"
+    should_respond_with 200, /<!DOCTYPE html PUBLIC.*>.*<h3>Start Here<\/h3>/m
+  end
+
+  it "downloads the index at /index.html" do
+    get "/"
+    should_respond_with 200, /<!DOCTYPE html PUBLIC.*>.*<h3>Start Here<\/h3>/m
+  end
+
+  it "downloads contribute at /contribute.html" do
+    get "/contribute.html"
+    should_respond_with 200, /<!DOCTYPE html PUBLIC.*>.*<h2>Contribute<\/h2>/m
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,22 @@
+require "fileutils"
+require "pathname"
+require "support/cli"
+require "support/rack"
+
+RSpec.configure do |config|
+  include SpecHelpers
+
+  def tmp
+    @tmp ||= Pathname.new(File.expand_path("../../tmp", __FILE__))
+  end
+
+  def reset_tmp
+    FileUtils.rm_rf(tmp)
+    FileUtils.mkdir_p(tmp)
+    Dir.chdir(tmp)
+  end
+
+  config.before(:suite) do
+    reset_tmp
+  end
+end

data/spec/support/cli.rb

@@ -0,0 +1,113 @@
+require "guides"
+require "guides/cli"
+
+module SpecHelpers
+  attr_reader :stdin, :stdout, :stderr
+
+  def env
+    @env ||= {}
+  end
+
+  def guides(*argv)
+    opts = Hash === argv.last ? argv.pop : {}
+
+    kill!
+    create_pipes
+
+    @pid = Process.fork do
+      Dir.chdir opts[:chdir] if opts[:chdir]
+
+      @stdout.close
+      @stdin.close
+      @stderr.close
+
+      STDOUT.reopen @stdout_child
+      STDIN.reopen  @stdin_child
+
+      if opts[:track_stderr] || argv.first == 'preview'
+        STDERR.reopen @stderr_child
+      end
+
+      env.each do |key, val|
+        ENV[key] = val
+      end
+
+      Guides::CLI.start(argv)
+    end
+
+    if argv.first == 'preview'
+      wait_for_preview_server
+    end
+
+    @stdout_child.close
+    @stdin_child.close
+    @stderr_child.close
+    @pid
+  end
+
+  def wait_for_preview_server
+    s = TCPSocket.new('0.0.0.0', 9292)
+  rescue Errno::ECONNREFUSED
+    sleep 0.2
+    retry
+  ensure
+    s.close
+  end
+
+  def out_until_block(io = stdout)
+    # read 1 first so we wait until the process is done processing the last write
+    chars = nil
+
+    IO.select( [ io ] )
+
+    chars = io.read(1)
+    sleep 0.05
+
+    loop do
+      chars << io.read_nonblock(1000)
+      sleep 0.05
+    end
+  rescue Errno::EAGAIN, EOFError => e
+    chars || ""
+  end
+
+  def input(line, opts = {})
+    if on = opts[:on]
+      should_block_on on
+    end
+    stdin << "#{line}\n"
+  end
+
+  def wait
+    return unless @pid
+
+    pid, status = Process.wait2(@pid, 0)
+
+    @exit_status = status
+    @pid = nil
+  end
+
+  def exit_status
+    wait
+    @exit_status
+  end
+
+  def kill!
+    Process.kill(9, @pid) if @pid
+  end
+
+  def out
+    stdout.read
+  end
+
+  def err
+    stderr.read
+  end
+
+  def create_pipes
+    @stdout, @stdout_child = IO.pipe
+    @stdin_child, @stdin   = IO.pipe
+    @stderr, @stderr_child = IO.pipe
+  end
+end
+

data/spec/support/rack.rb

@@ -0,0 +1,112 @@
+require 'uri'
+require 'faraday'
+require 'rack'
+require 'webrick'
+require 'socket'
+
+Thread.abort_on_exception = true
+
+module SpecHelpers
+  RACK_ENV_KEYS = [ 'PATH_INFO', 'REQUEST_METHOD', 'QUERY_STRING', 'rack.input',
+                    'HTTP_X_ZOMG' ]
+
+  def self.launch_test_server
+    @test_server ||= begin
+      app = lambda do |env|
+        ret = env.slice(*RACK_ENV_KEYS)
+        ret['rack.input'] = ret['rack.input'].read if ret['rack.input']
+        [ 200, { 'Content-Type' => 'text/plain' }, ret.inspect ]
+      end
+
+      t = Thread.new do
+        logger = WEBrick::Log.new(nil, WEBrick::BasicLog::WARN)
+        Rack::Handler::WEBrick.run(app, :Host   => '0.0.0.0', :Port => 9293,
+                                        :Logger => logger, :AccessLog => [])
+      end
+
+      begin
+        s = TCPSocket.new('0.0.0.0', 9293)
+      rescue Errno::ECONNREFUSED
+        sleep 0.2
+        retry
+      end
+
+      s.close
+      t
+    end
+  end
+
+  def launch_test_server
+    SpecHelpers.launch_test_server
+  end
+
+  %w( get post put delete head ).each do |method|
+    class_eval <<-RUBY
+      def #{method}(uri, *args)
+        request(:#{method}, uri, *args)
+      end
+    RUBY
+  end
+
+  attr_reader :response
+  attr_reader :host
+
+  def host!(host)
+    @host = host
+  end
+
+  def request(method, uri, *args)
+    uri     = URI(uri)
+    host    = uri.host   || @host
+    scheme  = uri.scheme || 'http'
+    headers = Hash === args.last ? args.pop : {}
+
+    if host == :preview
+      ip = host = 'http://localhost:9292'
+    else
+      ip = ENV['STROBEAPP_URL']
+    end
+
+    headers['Host'] = host
+    headers['Authorization'] = 'basic x:x' # hac to bypass varnish
+
+    conn = Faraday::Connection.new(:url => ip) do |c|
+      c.use Faraday::Adapter::NetHttp
+      c.headers.merge! headers
+    end
+
+    path = uri.path
+    path = "#{path}?#{uri.query}" if uri.query
+
+    @response = conn.run_request(method, path, args.first, {})
+  end
+
+  def should_respond_with(status, body = nil, hdrs = {})
+    @response.status.should == status
+
+    if body.is_a?(Regexp)
+      @response.body.should =~ body
+    elsif body
+      @response.body.should == body
+    end
+
+    hdrs.each do |hdr, val|
+      @response.headers[hdr].should == val
+    end
+  end
+
+  def should_have_env(env)
+    @response.status.should == 200
+    empty  = RACK_ENV_KEYS - env.keys
+    actual = eval(@response.body)
+
+    env.each do |key, val|
+      actual[key].should == val
+    end
+
+    empty.each do |key|
+      actual[key].should be_blank
+    end
+  end
+end
+

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 5
-  - 0
-  version: 0.5.0
+  - 6
+  - 1
+  version: 0.6.1
 platform: ruby
 authors: 
 - Yehuda Katz
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-01-04 00:00:00 -08:00
+date: 2011-01-13 00:00:00 -08:00
 default_executable: guides
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -92,6 +92,21 @@ dependencies:
         version: 0.14.6
   type: :runtime
   version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: thin
+  prerelease: false
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 2
+        - 7
+        version: 1.2.7
+  type: :runtime
+  version_requirements: *id006
 description: A tool for creating version controlled guides for open source projects, based on the Rails Guides framework
 email: 
 - wycats@gmail.com
@@ -104,6 +119,8 @@ extra_rdoc_files: []
 files: 
 - .gitignore
 - Gemfile
+- RELEASES.yml
+- Rakefile
 - bin/guides
 - guides.gemspec
 - lib/guides.rb
@@ -113,6 +130,7 @@ files:
 - lib/guides/indexer.rb
 - lib/guides/levenshtein.rb
 - lib/guides/new.rb
+- lib/guides/preview.rb
 - lib/guides/templates/assets/images/book_icon.gif
 - lib/guides/templates/assets/images/bullet.gif
 - lib/guides/templates/assets/images/chapters_icon.gif
@@ -219,6 +237,12 @@ files:
 - lib/guides/textile_extensions.rb
 - lib/guides/version.rb
 - lib/guides/w3c_validator.rb
+- spec/build_spec.rb
+- spec/new_spec.rb
+- spec/preview_spec.rb
+- spec/spec_helper.rb
+- spec/support/cli.rb
+- spec/support/rack.rb
 has_rdoc: true
 homepage: http://yehudakatz.com
 licenses: []
@@ -253,5 +277,10 @@ rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
 summary: Extracting the Rails Guides framework for the rest of us
-test_files: []
-
+test_files: 
+- spec/build_spec.rb
+- spec/new_spec.rb
+- spec/preview_spec.rb
+- spec/spec_helper.rb
+- spec/support/cli.rb
+- spec/support/rack.rb