nanoc3 3.0.9 → 3.1.0a1

data/lib/nanoc3/helpers/blogging.rb

@@ -2,76 +2,59 @@
 
 module Nanoc3::Helpers
 
-  # Nanoc3::Helpers::Blogging provides some functionality for building blogs,
-  # such as finding articles and constructing feeds.
+  # Provides functionality for building blogs, such as finding articles and
+  # constructing feeds.
   #
   # This helper has a few requirements. First, all blog articles should have
   # the following attributes:
   #
-  # * 'kind', set to 'article'.
+  # * `kind` — Set to `"article"`
   #
-  # * 'created_at', set to the creation timestamp.
+  # * `created_at` — The article’s publication timestamp. This timestamp can
+  #   be in any format parseable by `Time.parse`.
   #
-  # Some functions in this blogging helper, such as the +atom_feed+ function,
+  # Some functions in this blogging helper, such as the {#atom_feed} function,
   # require additional attributes to be set; these attributes are described in
   # the documentation for these functions.
   #
-  # The two main functions are sorted_articles and atom_feed.
-  #
-  # To activate this helper, +include+ it, like this:
-  #
-  #   include Nanoc3::Helpers::Blogging
+  # The two main functions are {#sorted_articles} and {#atom_feed}.
   module Blogging
 
-    # Returns an unsorted list of articles.
+    # Returns an unsorted list of articles, i.e. items where the `kind`
+    # attribute is set to `"article"`.
+    #
+    # @return [Array] An array containing all articles
     def articles
       @items.select { |item| item[:kind] == 'article' }
     end
 
-    # Returns a list of articles, sorted by descending creation date (so newer
-    # articles appear first).
+    # Returns a sorted list of articles, i.e. items where the `kind`
+    # attribute is set to `"article"`. Articles are sorted by descending
+    # creation date, so newer articles appear before older articles.
+    #
+    # @return [Array] A sorted array containing all articles
     def sorted_articles
       require 'time'
-      articles.sort_by do |a|
-        time = a[:created_at]
-        time.is_a?(String) ? Time.parse(time) : time
-      end.reverse
+      articles.sort_by { |a| t = a[:created_at] ; t.is_a?(String) ? Time.parse(t) : t }.reverse
     end
 
     # Returns a string representing the atom feed containing recent articles,
-    # sorted by descending creation date. +params+ is a hash where the
-    # following keys can be set:
-    #
-    # +limit+:: The maximum number of articles to show. Defaults to 5.
-    #
-    # +articles+:: A list of articles to include in the feed. Defaults to the
-    #              list of articles returned by the articles function.
-    #
-    # +content_proc+:: A proc that returns the content of the given article,
-    #                  passed as a parameter. By default, given the argument
-    #                  +article+, this proc will return
-    #                  +article.reps[0].content+. This function may not return
-    #                  nil.
-    #
-    # +excerpt_proc+:: A proc that returns the excerpt of the given article,
-    #                  passed as a parameter. By default, given the argument
-    #                  +article+, this proc will return +article.excerpt+.
-    #                  This function may return nil.
+    # sorted by descending creation date.
     #
     # The following attributes must be set on blog articles:
     #
-    # * 'title', containing the title of the blog post.
+    # * `title` — The title of the blog post
     #
-    # * all other attributes mentioned above.
+    # * `kind` and `created_at` (described above)
     #
     # The following attributes can optionally be set on blog articles to
     # change the behaviour of the Atom feed:
     #
-    # * 'excerpt', containing an excerpt of the article, usually only a few
+    # * `excerpt` — An excerpt of the article, which is usually only a few
     #   lines long.
     #
-    # * 'custom_path_in_feed', containing the path that will be used instead
-    #   of the normal path in the feed. This can be useful when including
+    # * `custom_path_in_feed` — The path that will be used instead of the
+    #   normal path in the feed. This can be useful when including
     #   non-outputted items in a feed; such items could have their custom feed
     #   path set to the blog path instead, for example.
     #
@@ -82,34 +65,63 @@ module Nanoc3::Helpers
     #
     # The site configuration will need to have the following attributes:
     #
-    # * 'base_url', containing the URL to the site, without trailing slash.
-    #   For example, if the site is at "http://example.com/", the base_url
-    #   would be "http://example.com".
+    # * `base_url` — The URL to the site, without trailing slash. For
+    #   example, if the site is at “http://example.com/”, the `base_url`
+    #   would be “http://example.com”.
     #
     # The feed item will need to have the following attributes:
     #
-    # * 'title', containing the title of the feed, which is usually also the
-    #   title of the blog.
+    # * `title` — The title of the feed, which is usually also the title of
+    #   the blog.
     #
-    # * 'author_name', containing the name of the item's author. This will
-    #   likely be a global attribute, unless the site is managed by several
-    #   people/
+    # * `author_name` — The name of the item’s author.
     #
-    # * 'author_uri', containing the URI for the item's author, such as the
-    #   author's web site URL. This will also likely be a global attribute.
+    # * `author_uri` — The URI for the item’s author, such as the author’s
+    #   web site URL.
     #
     # The feed item can have the following optional attributes:
     #
-    # * 'feed_url', containing the custom URL of the feed. This can be useful
-    #   when the private feed URL shouldn't be exposed; for example, when
-    #   using FeedBurner this would be set to the public FeedBurner URL.
+    # * `feed_url` — The custom URL of the feed. This can be useful when the
+    #   private feed URL shouldn’t be exposed; for example, when using
+    #   FeedBurner this would be set to the public FeedBurner URL.
+    #
+    # To construct a feed, create a new item and make sure that it is
+    # filtered with `:erb` or `:erubis`; it should not be laid out. Ensure
+    # that it is routed to the proper path, e.g. `/blog.xml`. It may also be
+    # useful to set the `is_hidden` attribute to true, so that helpers such
+    # as the sitemap helper will ignore the item. The content of the feed
+    # item should be `<%= atom_feed %>`.
+    #
+    # @example Defining compilation and routing rules for a feed item
+    #
+    #   compile '/blog/feed/' do
+    #     filter :erb
+    #   end
+    #
+    #   route '/blog/feed/' do
+    #     '/blog.xml'
+    #   end
     #
-    # To construct a feed, create a blank item with no layout, only the 'erb'
-    # (or 'erubis') filter, and an 'xml' extension. It may also be useful to
-    # set 'is_hidden' to true, so that helpers such as the sitemap helper will
-    # ignore the item. The content of the feed item should be:
+    # @example Limiting the number of items in a feed
     #
-    #   <%= atom_feed %>
+    #   <%= atom_feed :limit => 5 %>
+    #
+    # @option params [Number] :limit (5) The maximum number of articles to
+    #   show
+    #
+    # @option params [Array] :articles (sorted_articles) A list of articles to
+    #   include in the feed
+    #
+    # @option params [Proc] :content_proc (->{ |article|
+    #   article.compiled_content(:snapshot => :pre) }) A proc that returns the
+    #   content of the given article, which is passed as a parameter. This
+    #   function may not return nil.
+    #
+    # @option params [proc] :excerpt_proc (->{ |article| article[:excerpt] })
+    #   A proc that returns the excerpt of the given article, passed as a
+    #   parameter. This function should return nil if there is no excerpt.
+    #
+    # @return [String] The generated feed content
     def atom_feed(params={})
       require 'builder'
       require 'time'
@@ -117,7 +129,7 @@ module Nanoc3::Helpers
       # Extract parameters
       limit             = params[:limit] || 5
       relevant_articles = params[:articles] || articles || []
-      content_proc      = params[:content_proc] || lambda { |a| a.reps[0].content_at_snapshot(:pre) }
+      content_proc      = params[:content_proc] || lambda { |a| a.compiled_content(:snapshot => :pre) }
       excerpt_proc      = params[:excerpt_proc] || lambda { |a| a[:excerpt] }
 
       # Check config attributes
@@ -145,10 +157,7 @@ module Nanoc3::Helpers
       end
 
       # Get sorted relevant articles
-      sorted_relevant_articles = relevant_articles.sort_by do |a|
-        time = a[:created_at]
-        time.is_a?(String) ? Time.parse(time) : time
-      end.reverse.first(limit)
+      sorted_relevant_articles = relevant_articles.sort_by { |a| Time.parse(a[:created_at]) }.reverse.first(limit)
 
       # Get most recent article
       last_article = sorted_relevant_articles.first
@@ -167,8 +176,7 @@ module Nanoc3::Helpers
         xml.title   @item[:title]
 
         # Add date
-        time = last_article[:created_at]
-        xml.updated((time.is_a?(String) ? Time.parse(time) : time).to_iso8601_time)
+        xml.updated Time.parse(last_article[:created_at]).to_iso8601_time
 
         # Add links
         xml.link(:rel => 'alternate', :href => root_url)
@@ -192,8 +200,7 @@ module Nanoc3::Helpers
             xml.title     a[:title], :type => 'html'
 
             # Add dates
-            time = a[:created_at]
-            xml.published((time.is_a?(String) ? Time.parse(time) : time).to_iso8601_time)
+            xml.published Time.parse(a[:created_at]).to_iso8601_time
             xml.updated   a.mtime.to_iso8601_time
 
             # Add link
@@ -212,6 +219,10 @@ module Nanoc3::Helpers
 
     # Returns the URL for the given item. It will return the URL containing
     # the custom path in the feed if possible, otherwise the normal path.
+    #
+    # @param [Nanoc3::Item] item The item for which to fetch the URL.
+    #
+    # @return [String] The URL of the given item
     def url_for(item)
       # Check attributes
       if @site.config[:base_url].nil?
@@ -219,7 +230,7 @@ module Nanoc3::Helpers
       end
 
       # Get path
-      path = item[:custom_path_in_feed] || item.reps[0].path
+      path = item[:custom_path_in_feed] || item.path
       return nil if path.nil?
 
       # Build URL
@@ -228,28 +239,33 @@ module Nanoc3::Helpers
 
     # Returns the URL of the feed. It will return the custom feed URL if set,
     # or otherwise the normal feed URL.
+    #
+    # @return [String] The URL of the feed
     def feed_url
       # Check attributes
       if @site.config[:base_url].nil?
         raise RuntimeError.new('Cannot build Atom feed: site configuration has no base_url')
       end
 
-      @item[:feed_url] || @site.config[:base_url] + @item.reps[0].path
+      @item[:feed_url] || @site.config[:base_url] + @item.path
     end
 
     # Returns an URI containing an unique ID for the given item. This will be
     # used in the Atom feed to uniquely identify articles. These IDs are
-    # created using a procedure suggested by Mark Pilgrim in this blog post:
-    # http://diveintomark.org/archives/2004/05/28/howto-atom-id.
+    # created using a procedure suggested by Mark Pilgrim and described in his
+    # [“How to make a good ID in Atom” blog post]
+    # (http://diveintomark.org/archives/2004/05/28/howto-atom-id).
+    #
+    # @param [Nanoc3::Item] item The item for which to create an atom tag
+    #
+    # @return [String] The atom tag for the given item
     def atom_tag_for(item)
       require 'time'
 
       hostname, base_dir = %r{^.+?://([^/]+)(.*)$}.match(@site.config[:base_url])[1..2]
+      formatted_date     = Time.parse(item[:created_at]).to_iso8601_date
 
-      time = item[:created_at]
-      formatted_date = (time.is_a?(String) ? Time.parse(time) : time).to_iso8601_date
-
-      'tag:' + hostname + ',' + formatted_date + ':' + base_dir + (item.reps[0].path || item.identifier)
+      'tag:' + hostname + ',' + formatted_date + ':' + base_dir + (item.path || item.identifier)
     end
 
   end

data/lib/nanoc3/helpers/breadcrumbs.rb

@@ -2,20 +2,28 @@
 
 module Nanoc3::Helpers
 
-  # Nanoc3::Helpers::Breadcrumbs provides support for breadcrumbs, which allow
-  # the user to go up in the page hierarchy.
+  # Provides support for breadcrumbs, which allow the user to go up in the
+  # page hierarchy.
   module Breadcrumbs
 
-    # Returns the breadcrumbs trail as an array. Higher items (items that are
-    # closer to the root) come before lower items.
+    # Creates a breadcrumb trail leading from the current item to its parent,
+    # to its parent’s parent, etc, until the root item is reached. This
+    # function does not require that each intermediate item exist; for
+    # example, if there is no `/foo/` item, breadcrumbs for a `/foo/bar/` item
+    # will contain a `nil` element.
+    #
+    # @return [Array] The breadcrumbs, starting with the root item and ending
+    #   with the item itself
     def breadcrumbs_trail
-      trail = [] 
-      item = @item 
+      trail = []
+      current_identifier = @item.identifier
 
-      begin
-        trail.unshift(item) 
-        item = item.parent 
-      end until item.nil?
+      loop do
+        item = @items.find { |i| i.identifier == current_identifier }
+        trail.unshift(item)
+        break if current_identifier == '/'
+        current_identifier = current_identifier.sub(/[^\/]+\/$/, '')
+      end
 
       trail
     end

data/lib/nanoc3/helpers/capturing.rb

@@ -2,10 +2,8 @@
 
 module Nanoc3::Helpers
 
-  # Nanoc3::Helpers::Capturing provides a content_for method, which allows
-  # content to be "captured" on one item and reused elsewhere.
-  #
-  # = Example
+  # Provides functionality for “capturing” content in one place and reusing
+  # this content elsewhere.
   #
   # For example, suppose you want the sidebar of your site to contain a short
   # summary of the item. You could put the summary in the meta file, but
@@ -14,47 +12,44 @@ module Nanoc3::Helpers
   # you write the summary on the item itself, but capture it, and print it in
   # the sidebar layout.
   #
-  # Captured content becomes part of the item. For example, a sidebar layout
-  # could look like this:
+  # @example Capturing content into a `content_for_summary` attribute
+  #   <% content_for :summary do %>
+  #     <p>On this item, nanoc is introduced, blah blah.</p>
+  #   <% end %>
   #
+  # @example Showing captured content in a sidebar
   #   <div id="sidebar">
   #     <h3>Summary</h3>
   #     <%= @item[:content_for_summary] || '(no summary)' %>
   #   </div>
-  #
-  # To put something inside that content_for_summary variable, capture it
-  # using the content_for function. In the about item, for example:
-  #
-  #   <% content_for :summary do %>
-  #     <p>On this item, nanoc is introduced, blah blah.</p>
-  #   <% end %>
-  #
-  # When the site is compiled, the sidebar of the about item will say “On
-  # this item, the purpose of nanoc is described, blah blah blah,” as
-  # expected.
-  #
-  # This helper has been tested with ERB and Haml.
-  #
-  # To activate this helper, +include+ it, like this:
-  #
-  #   include Nanoc3::Helpers::Capturing
   module Capturing
 
-    # Captures the content inside the block into a item attribute named
-    # "content_for_" followed by the given name. The content of the block
-    # itself will not be outputted.
+    # Captures the content inside the block and stores it in an item
+    # attribute named `content_for_` followed by the given name. The
+    # content of the block itself will not be outputted.
+    #
+    # @param [Symbol, String] The base name of the attribute into which
+    #   the content should be stored
+    #
+    # @return [void]
     def content_for(name, &block)
       eval("@item[:content_for_#{name.to_s}] = capture(&block)")
     end
 
-    # Evaluates the given block and returns the result. The block is not outputted.
-    def capture(*args, &block)
+    # Evaluates the given block and returns the result. The contents of the
+    # block is not outputted.
+    #
+    # This function has been tested with ERB and Haml. Other filters may not
+    # work correctly.
+    #
+    # @return [String] The captured result
+    def capture(&block)
       # Get erbout so far
       erbout = eval('_erbout', block.binding)
       erbout_length = erbout.length
 
       # Execute block
-      block.call(*args)
+      block.call
 
       # Get new piece of erbout
       erbout_addition = erbout[erbout_length..-1]

data/lib/nanoc3/helpers/filtering.rb

@@ -2,28 +2,31 @@
 
 module Nanoc3::Helpers
 
-  # Nanoc3::Helpers::Filtering provides a filter method, which allows parts of
-  # an item to be filtered.
-  #
-  # For example, the following piece of code only runs the "rubypants" filter
-  # on the second paragraph:
-  #
-  #   <p>Lorem ipsum dolor sit amet...</p>
-  #   <% filter :rubypants do %>
-  #     <p>Consectetur adipisicing elit...</p>
-  #   <% end %>
-  #
-  # This helper has been tested with ERB and Haml.
-  #
-  # To activate this helper, +include+ it, like this:
-  #
-  #   include Nanoc3::Helpers::Filtering
+  # Provides functionality for filtering parts of an item or a layout.
   module Filtering
 
     require 'nanoc3/helpers/capturing'
     include Nanoc3::Helpers::Capturing
 
-    # Filters the content in the given block and outputs it.
+    # Filters the content in the given block and outputs it. This function
+    # does not return anything; instead, the filtered contents is directly
+    # appended to the output buffer (`_erbout`).
+    #
+    # This function has been tested with ERB and Haml. Other filters may not
+    # work correctly.
+    #
+    # @example Running a filter on a part of an item or layout
+    #   <p>Lorem ipsum dolor sit amet...</p>
+    #   <% filter :rubypants do %>
+    #     <p>Consectetur adipisicing elit...</p>
+    #   <% end %>
+    #
+    # @param [Symbol] filter_name The name of the filter to run on the
+    #   contents of the block
+    #
+    # @param [Hash] argument Arguments to pass to the filter
+    #
+    # @return [void]
     def filter(filter_name, arguments={}, &block)
       # Capture block
       data = capture(&block)

data/lib/nanoc3/helpers/html_escape.rb

@@ -2,12 +2,15 @@
 
 module Nanoc3::Helpers
 
-  # Nanoc3::Helpers::HTMLEscape contains functionality for HTML-escaping
-  # strings.
+  # Contains functionality for HTML-escaping strings.
   module HTMLEscape
 
-    # Returns the HTML-escaped representation of the given string. Only &, <,
-    # > and " are escaped.
+    # Returns the HTML-escaped representation of the given string. Only `&`,
+    # `<`, `>` and `"` are escaped.
+    #
+    # @param [String] string The string to escape
+    #
+    # @return [String] The escaped string
     def html_escape(string)
       string.gsub('&', '&amp;').
              gsub('<', '&lt;').

data/lib/nanoc3/helpers/link_to.rb

@@ -2,11 +2,7 @@
 
 module Nanoc3::Helpers
 
-  # Nanoc3::Helpers::LinkTo contains functions for linking to items.
-  #
-  # To activate this helper, +include+ it, like this:
-  #
-  #   include Nanoc3::Helpers::LinkTo
+  # Contains functions for linking to items and item representations.
   module LinkTo
 
     require 'nanoc3/helpers/html_escape'
@@ -15,30 +11,39 @@ module Nanoc3::Helpers
     # Creates a HTML link to the given path or item representation, and with
     # the given text. All attributes of the `a` element, including the `href`
     # attribute, will be HTML-escaped; the contents of the `a` element, which
-    # can contain markup, will not be HTML-escaped.
+    # can contain markup, will not be HTML-escaped. The HTML-escaping is done
+    # using {Nanoc3::Helpers::HTMLEscape#html_escape}.
     #
-    # +path_or_rep+:: the URL or path (a String) that should be linked to, or
-    #                 the item representation that should be linked to.
+    # @param [String] text The visible link text
     #
-    # +text+:: the visible link text.
+    # @param [String, Nanoc3::Item, Nanoc3::ItemRep] target The path/URL,
+    #   item or item representation that should be linked to
     #
-    # +attributes+:: a hash containing HTML attributes that will be added to
-    #                the link.
+    # @param [Hash] attributes A hash containing HTML attributes (e.g.
+    #   `rel`, `title`, …) that will be added to the link.
     #
-    # Examples:
+    # @return [String] The link text
     #
+    # @example Linking to a path
     #   link_to('Blog', '/blog/')
     #   # => '<a href="/blog/">Blog</a>'
     #
-    #   item_rep = @items.find { |i| i.item_id == 'special' }.reps[0]
-    #   link_to('Special Item', item_rep)
-    #   # => '<a href="/special_item/">Special Item</a>'
+    # @example Linking to an item
+    #   about = @items.find { |i| i.identifier == '/about/' }
+    #   link_to('About Me', about)
+    #   # => '<a href="/about.html">About Me</a>'
     #
+    # @example Linking to an item representation
+    #   about = @items.find { |i| i.identifier == '/about/' }
+    #   link_to('My vCard', about.rep(:vcard))
+    #   # => '<a href="/about.vcf">My vCard</a>'
+    #
+    # @example Linking with custom attributes
     #   link_to('Blog', '/blog/', :title => 'My super cool blog')
-    #   # => '<a href="/blog/" title="My super cool blog">Blog</a>
-    def link_to(text, path_or_rep, attributes={})
+    #   # => '<a title="My super cool blog" href="/blog/">Blog</a>'
+    def link_to(text, target, attributes={})
       # Find path
-      path = path_or_rep.is_a?(String) ? path_or_rep : path_or_rep.path
+      path = target.is_a?(String) ? target : target.path
 
       # Join attributes
       attributes = attributes.inject('') do |memo, (key, value)|
@@ -50,52 +55,57 @@ module Nanoc3::Helpers
     end
 
     # Creates a HTML link using link_to, except when the linked item is the
-    # current one. In this case, a span element with class "active" and with
-    # the given text will be returned. The HTML-escaping rules for `link_to`
-    # apply here as well.
+    # current one. In this case, a span element with class “active” and with
+    # the given text will be returned. The HTML-escaping rules for
+    # {#link_to} apply here as well.
+    #
+    # @param [String] text The visible link text
+    #
+    # @param [String, Nanoc3::Item, Nanoc3::ItemRep] target The path/URL,
+    #   item or item representation that should be linked to
     #
-    # Examples:
+    # @param [Hash] attributes A hash containing HTML attributes (e.g.
+    #   `rel`, `title`, …) that will be added to the link.
     #
+    # @return [String] The link text
+    #
+    # @example Linking to a different page
     #   link_to_unless_current('Blog', '/blog/')
     #   # => '<a href="/blog/">Blog</a>'
     #
-    #   link_to_unless_current('This Item', @item_rep)
-    #   # => '<span class="active">This Item</span>'
-    def link_to_unless_current(text, path_or_rep, attributes={})
+    # @example Linking to the same page
+    #   link_to_unless_current('This Item', @item)
+    #   # => '<span class="active" title="You\'re here.">This Item</span>'
+    def link_to_unless_current(text, target, attributes={})
       # Find path
-      path = path_or_rep.is_a?(String) ? path_or_rep : path_or_rep.path
+      path = target.is_a?(String) ? target : target.path
 
-      if @item_rep and @item_rep.path == path
+      if @item_rep && @item_rep.path == path
         # Create message
         "<span class=\"active\" title=\"You're here.\">#{text}</span>"
       else
-        link_to(text, path_or_rep, attributes)
+        link_to(text, target, attributes)
       end
     end
 
     # Returns the relative path from the current item to the given path or
     # item representation. The returned path will not be HTML-escaped.
     #
-    # +path_or_rep+:: the URL or path (a String) to where the relative should
-    #                 point, or the item representation to which the relative
-    #                 should point.
+    # @param [String, Nanoc3::Item, Nanoc3::ItemRep] target The path/URL,
+    #   item or item representation to which the relative path should be
+    #   generated
     #
-    # Example:
+    # @return [String] The relative path to the target
     #
+    # @example
     #   # if the current item's path is /foo/bar/
-    #   relative_path('/foo/qux/')
+    #   relative_path_to('/foo/qux/')
     #   # => '../qux/'
     def relative_path_to(target)
       require 'pathname'
 
       # Find path
-      if target.is_a?(String)
-        path = target
-      elsif target.respond_to?(:reps)
-        path = target.reps.find { |r| r.name == :default }.path
-      else
-        path = target.path
-      end
+      path = target.is_a?(String) ? target : target.path
 
       # Get source and destination paths
       dst_path   = Pathname.new(path)
@@ -111,7 +121,7 @@ module Nanoc3::Helpers
 
       # Add trailing slash if necessary
       if dst_path.to_s[-1,1] == '/'
-        relative_path += '/'
+        relative_path << '/'
       end
 
       # Done