pith 0.0.5 → 0.0.6

data/README.markdown

@@ -1,28 +1,21 @@
 Pith
 ====
 
-Pith is a static web-site generator, written in Ruby.
+Pith is a static website generator, written in Ruby.
 
 Using Pith, you can:
 
-* __Express yourself succintly__ using Markdown or Textile.
+* Lay-out your page designs in [Haml][haml], ERb, or Liquid.
 
-* __Layout your pages__ written in ERb, [Haml][haml], or Liquid.
+* Style things up using [Sass][sass].
 
-* __Style things up using__ [Sass][sass].
+* Succintly add content using Markdown or Textile.
 
-* __Encapsulate common markup__ in "layout" and "partial" templates.
+* Encapsulate common markup in "layout" and "partial" templates.
 
-* __Easily link pages and resources__ using relative links.
+* Easily link pages (and resources) using relative links.
 
-* __Quickly test changes__ using the built-in web-server.
-
-* __Define custom helper-methods__ to increase expressiveness.
-
-Why Pith?
----------
-
-Why another static web-site generator, when there are other good options out there?  Pith's main differentiating factor is that structure of the output slavishly mirrors the structure of the input; there are no magic input directories for layouts, or dynamic content, or anything else.
+* Test changes quickly using the built-in web-server.
 
 Install it
 ----------
@@ -31,6 +24,105 @@ Pith is packaged as a Ruby gem.  Assuming you have Ruby, install it thusly:
 
     gem install pith
 
+Quickstart
+----------
+
+Create an input directory for your site (wherever you want), and pop some files into it:
+
+    SITE/
+      _pith/
+      images/
+        logo.png
+      index.html.haml
+
+The only requirement is the existance of a sub-directory called "`_pith`".  Pith checks that it's present, to prevent you accidently treating you entire home-directory as website input.
+
+Next, use the `pith build` command to convert your inputs into a functioning website.
+
+    $ pith -i SITE build
+    Generating to "SITE/_out"
+    --(copy)-->   images/logo.png
+    --(haml)-->   index.html
+
+Any input file with an extension recognised by [Tilt][tilt] is considered to be a template, and will be dynamically evaluated.  Formats supported by Tilt include:
+
+- [Markdown](http://daringfireball.net/projects/markdown/) (`markdown`, `md`)
+- [Textile](http://redcloth.org/hobix.com/textile/) (`textile`)
+- [Haml][haml] (`haml`)
+- [Erb](http://ruby-doc.org/stdlib/libdoc/erb/rdoc/classes/ERB.html) (`erb`)
+- [Sass][sass] (`sass`)
+- [CoffeeScript](http://jashkenas.github.com/coffee-script/) (`coffee`)
+
+Anything else is just copied verbatim into the generated site.
+
+Partials
+--------
+
+Templates can include other templates, e.g.
+
+     = include("_header.haml")
+
+Note the leading underscore ("_").  Any input file (or directory) beginning with an underscore is ignored when generating outputs.
+
+When including, you can pass local variables, e.g.
+
+    = include("_list.haml", :items => [1,2,3])
+
+which can be accessed in the included template:
+
+    %ul
+      - items.each do |i|
+        %li= i
+
+Layouts
+-------
+
+Layout templates are a bit like partials, except that they take a block, e.g.
+
+    = inside "_mylayout.haml" do
+      %p Some content
+
+Use "`yield`" to embed the block's content within the layout:
+
+    !!!
+    %html
+      %body
+        .header
+          ... blah blah ...
+        .main
+          = yield
+
+Relative links
+--------------
+
+It's sensible to use relative URIs when linking to other pages (and resources) in your static site, making the site easier to relocate.  But generating relative-links from partials and layouts is tricky.  Pith makes it easy with the "`href`" function:
+
+    %a{:href => href("other.html")} Other page
+
+    %img{:src => href("/images/logo.png")}
+
+Any path beginning with a slash ("/") is resolved relative to the root of the site; anything else is resolve relative to the current input-file (even if that happens to be a layout or partial).  Either way, "`href`" always returns a relative link.
+
+There's also a "`link`" function, for even easier hyper-linking:
+
+    link("other.html", "Other page")
+    
+Built-in web-server
+-------------------
+
+For quick prototyping, pith includes a simple HTTP server.  Start it by using the "`serve`" command, rather than "`build`"
+
+    $ pith -i SITE serve
+    Generating to "SITE/_out"
+    --(copy)-->   images/logo.png
+    --(haml)-->   index.html
+    Taking the Pith at "http://localhost:4321"
+    >> Thin web server (v1.2.7 codename No Hup)
+    >> Maximum connections set to 1024
+    >> Listening on 0.0.0.0:4321, CTRL+C to stop
+
+Pith will incrementally re-build the site as you browse -- that is, if you alter any input files, Pith will regenerate the affected outputs.
+
 [tilt]: http://github.com/rtomayko/tilt/
 [haml]: http://haml-lang.com
 [sass]: http://sass-lang.com

data/bin/pith

@@ -36,9 +36,14 @@ OptionParser.new do |opts|
   end
 end.parse!
 
+pith_dir = $input_dir + "_pith"
+unless pith_dir.directory?
+  $stderr.puts %(ERROR: No "#{pith_dir}" directory ... this doesn't look right!)
+  exit(1)
+end
+
 unless $output_dir
   $output_dir = $input_dir + "_out"
-  puts %{Generating to "#{$output_dir}"}
 end
 
 require "pith/project"
@@ -48,12 +53,14 @@ require "pith/console_logger"
 @project.logger = Pith::ConsoleLogger.new
 
 def build
+  puts %{Generating to "#{$output_dir}"}
   @project.build
 end
 
 def serve
   require "pith/server"
   port = 4321
+  build
   puts %{Taking the Pith at "http://localhost:#{port}"}
   Pith::Server.run(@project, :Port => port)
 end

data/features/helpers.feature

@@ -21,3 +21,31 @@ Scenario: call a helper from a template
   When I build the site
   
   Then output file "index.html" should contain "Hello, World"
+
+Scenario: change a helper
+
+  Given input file "_pith/config.rb" contains
+    """
+    project.helpers do
+      def greet(subject)
+        "Hello, #{subject}"
+      end
+    end
+    """
+
+  And input file "index.html.haml" contains "= greet('mate')"
+   
+  When I build the site
+
+  And I change input file "_pith/config.rb" to contain
+    """
+    project.helpers do
+      def greet(subject)
+        "Gidday, #{subject}"
+      end
+    end
+    """
+
+  And I rebuild the site
+  
+  Then output file "index.html" should contain "Gidday, mate"

data/features/step_definitions/build_steps.rb

@@ -18,6 +18,10 @@ When /^I change input file "([^\"]*)" to contain "([^\"]*)"$/ do |path, content|
   @inputs[path] = content
 end
 
+When /^I change input file "([^\"]*)" to contain$/ do |path, content|
+  @inputs[path] = content
+end
+
 When /^I (?:re)?build the site$/ do
   @project.logger.clear
   @project.build

data/features/step_definitions/build_steps.rb~

@@ -18,6 +18,10 @@ When /^I change input file "([^\"]*)" to contain "([^\"]*)"$/ do |path, content|
   @inputs[path] = content
 end
 
+When /^I change input file "([^\"]*)" to contain$/ do |path, content|
+  @inputs[path] = content
+end
+
 When /^I (?:re)?build the site$/ do
   @project.logger.clear
   @project.build

data/lib/pith/input/template.rb

@@ -28,7 +28,7 @@ module Pith
       # Return true unless output needs to be re-generated.
       #
       def uptodate?
-        all_input_files && FileUtils.uptodate?(output_file, all_input_files)
+        dependencies && FileUtils.uptodate?(output_file, dependencies)
       end
 
       # Generate output for this template
@@ -39,7 +39,7 @@ module Pith
         output_file.open("w") do |out|
           out.puts(render_context.render(self))
         end
-        remember_dependencies(render_context.referenced_inputs)
+        @dependencies = render_context.dependencies
       end
 
       # Render this input using Tilt
@@ -112,11 +112,7 @@ module Pith
         end
       end
       
-      def remember_dependencies(referenced_inputs)
-        @all_input_files = referenced_inputs.map { |input| input.file }
-      end
-
-      attr_accessor :all_input_files
+      attr_accessor :dependencies
 
     end
 

data/lib/pith/input/template.rb~

@@ -39,7 +39,7 @@ module Pith
         output_file.open("w") do |out|
           out.puts(render_context.render(self))
         end
-        remember_dependencies(render_context.rendered_inputs)
+        remember_dependencies(render_context.referenced_inputs)
       end
 
       # Render this input using Tilt
@@ -112,8 +112,8 @@ module Pith
         end
       end
       
-      def remember_dependencies(rendered_inputs)
-        @all_input_files = rendered_inputs.map { |input| input.file }
+      def remember_dependencies(referenced_inputs)
+        @all_input_files = referenced_inputs.map { |input| input.file }
       end
 
       attr_accessor :all_input_files

data/lib/pith/project.rb

@@ -59,6 +59,7 @@ module Pith
     #
     def refresh
       @inputs = nil
+      @config_files = nil
     end
 
     def logger
@@ -74,6 +75,12 @@ module Pith
     def helper_module
       @helper_module ||= Module.new
     end
+
+    def config_files
+      @config_files ||= begin 
+        Pathname.glob("#{input_dir}/_pith/**")
+      end.to_set
+    end
     
     private
     
@@ -84,7 +91,7 @@ module Pith
         eval(config_file.read, binding, config_file)
       end
     end
-
+    
     def input_cache
       @input_cache ||= Hash.new do |h, cache_key|
         h[cache_key] = Input.new(self, cache_key.first)

data/lib/pith/project.rb~

@@ -59,6 +59,7 @@ module Pith
     #
     def refresh
       @inputs = nil
+      @config_files = nil
     end
 
     def logger
@@ -74,6 +75,12 @@ module Pith
     def helper_module
       @helper_module ||= Module.new
     end
+
+    def config_files
+      @config_files ||= begin 
+        Pathname.glob("#{input_dir}/_pith/**")
+      end.to_set
+    end
     
     private
     
@@ -84,7 +91,7 @@ module Pith
         eval(config_file.read, binding, config_file)
       end
     end
-
+    
     def input_cache
       @input_cache ||= Hash.new do |h, cache_key|
         h[cache_key] = Input.new(self, cache_key.first)

data/lib/pith/render_context.rb

@@ -11,7 +11,7 @@ module Pith
     def initialize(project)
       @project = project
       @input_stack = []
-      @referenced_inputs = Set.new
+      @dependencies = project.config_files.dup
       self.extend(project.helper_module)
     end
 
@@ -34,7 +34,7 @@ module Pith
       end
     end
 
-    attr_reader :referenced_inputs
+    attr_reader :dependencies
     
     def include(template_ref, locals = {}, &block)
       content_block = if block_given?
@@ -80,12 +80,12 @@ module Pith
     
     def find_input(path)
       input = project.input(path)
-      @referenced_inputs << input if input
+      @dependencies << input.file if input
       input
     end
     
     def with_input(input)
-      @referenced_inputs << input
+      @dependencies << input.file
       @input_stack.push(input)
       begin
         yield

data/lib/pith/render_context.rb~

@@ -11,7 +11,7 @@ module Pith
     def initialize(project)
       @project = project
       @input_stack = []
-      @rendered_inputs = Set.new
+      @referenced_inputs = project.config_files.dup
       self.extend(project.helper_module)
     end
 
@@ -26,7 +26,6 @@ module Pith
     end
     
     def render(input, locals = {}, &block)
-      @rendered_inputs << input
       with_input(input) do
         result = input.render(self, locals, &block)
         layout_ref = current_input.meta["layout"]
@@ -35,7 +34,7 @@ module Pith
       end
     end
 
-    attr_reader :rendered_inputs
+    attr_reader :referenced_inputs
     
     def include(template_ref, locals = {}, &block)
       content_block = if block_given?
@@ -62,7 +61,7 @@ module Pith
     def link(target_ref, label = nil)
       target_path = resolve_path(target_ref)
       label ||= begin
-        project.input(target_path).title
+        find_input(target_path).title
       rescue Pith::ReferenceError
         "???"
       end
@@ -79,7 +78,14 @@ module Pith
       current_input.resolve_path(ref)
     end
     
+    def find_input(path)
+      input = project.input(path)
+      @referenced_inputs << input if input
+      input
+    end
+    
     def with_input(input)
+      @referenced_inputs << input
       @input_stack.push(input)
       begin
         yield
@@ -89,7 +95,8 @@ module Pith
     end
     
     def render_ref(template_ref, locals = {}, &block)
-      template = project.input(resolve_path(template_ref))
+      template_path = resolve_path(template_ref)
+      template = find_input(template_path)
       render(template, locals, &block)
     end
 

data/lib/pith/version.rb

@@ -1,3 +1,3 @@
 module Pith
-  VERSION = "0.0.5".freeze
+  VERSION = "0.0.6".freeze
 end

data/lib/pith/version.rb~

@@ -1,3 +1,3 @@
 module Pith
-  VERSION = "0.0.4".freeze
+  VERSION = "0.0.5".freeze
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: pith
 version: !ruby/object:Gem::Version 
-  hash: 21
+  hash: 19
   prerelease: false
   segments: 
   - 0
   - 0
-  - 5
-  version: 0.0.5
+  - 6
+  version: 0.0.6
 platform: ruby
 authors: 
 - Mike Williams
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-09-01 00:00:00 +10:00
+date: 2010-09-02 00:00:00 +10:00
 default_executable: pith
 dependencies: 
 - !ruby/object:Gem::Dependency