nanoc 4.2.4 → 4.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d71e907ef0318683da05fb81149422628b700007
-  data.tar.gz: 8d6e28866ff7dc184b6738005c55e4f368c2f74c
+  metadata.gz: 42d007123a8daf12e6e2a49eec0faedcde6a9bfe
+  data.tar.gz: 6350ddff74b8837e0338e319bbb495dea5c8969b
 SHA512:
-  metadata.gz: ef183242bffb54bc9875275146912a1bc7f3bc84ed51fa77b032ba986952a8bd6895e18170b2580e6131e8deaee0591a2df94769917ae4bd829a566310f529e7
-  data.tar.gz: bf46729b4e0e8e682327b553460f9e3611b76ef74627441d3f1189d155bd6f978da4b3668dc08cf06fec6c00ad6dcdf694f6b2afe19814cc7436efda5b7df18a
+  metadata.gz: d67dfeb6608496945aa0cf341199b39fd137d7c12f790b1ae8eeea6ec28aa6491daf4f20cb566c5d61a50a78e870fb510a4ad8642820a902708d46e7b8b67696
+  data.tar.gz: 64a00a9a64a0b9d4b1e2e6a0953fae371b3a72e95b510b5264e9033cbda85ff877333220ef67d18c3af0dba822881251c1a8e6ade5da50dbb1f66ee4f8d18830

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    nanoc (4.2.4)
+    nanoc (4.3.0)
       cri (~> 2.3)
       hamster (~> 3.0)
       ref (~> 2.0)
@@ -39,12 +39,12 @@ GEM
       sass (>= 3.2, < 3.5)
     concurrent-ruby (1.0.2)
     contracts (0.14.0)
-    coveralls (0.8.14)
+    coveralls (0.8.15)
       json (>= 1.8, < 3)
       simplecov (~> 0.12.0)
       term-ansicolor (~> 1.3)
       thor (~> 0.19.1)
-      tins (~> 1.6.0)
+      tins (>= 1.6.0, < 2)
     crack (0.4.3)
       safe_yaml (~> 1.0.0)
     cri (2.7.0)
@@ -94,7 +94,7 @@ GEM
     fog-atmos (0.1.0)
       fog-core
       fog-xml
-    fog-aws (0.10.0)
+    fog-aws (0.11.0)
       fog-core (~> 1.38)
       fog-json (~> 1.0)
       fog-xml (~> 0.1)
@@ -128,7 +128,7 @@ GEM
       multi_json (~> 1.10)
     fog-local (0.3.0)
       fog-core (~> 1.27)
-    fog-openstack (0.1.8)
+    fog-openstack (0.1.11)
       fog-core (>= 1.40)
       fog-json (>= 1.0)
       ipaddress (>= 0.8)
@@ -174,7 +174,7 @@ GEM
     fog-voxel (0.1.0)
       fog-core
       fog-xml
-    fog-vsphere (0.8.0)
+    fog-vsphere (1.0.0)
       fog-core
       rbvmomi (~> 1.8)
     fog-xenserver (0.2.3)
@@ -210,8 +210,8 @@ GEM
     hashdiff (0.3.0)
     inflecto (0.0.2)
     ipaddress (0.8.3)
-    json (2.0.1)
-    kramdown (1.11.1)
+    json (2.0.2)
+    kramdown (1.12.0)
     less (2.6.0)
       commonjs (~> 0.2.7)
     libv8 (3.16.14.15)
@@ -238,7 +238,7 @@ GEM
     nokogiri (1.6.8)
       mini_portile2 (~> 2.1.0)
       pkg-config (~> 1.1.7)
-    notiffany (0.1.0)
+    notiffany (0.1.1)
       nenv (~> 0.1)
       shellany (~> 0.0)
     pandoc-ruby (2.0.1)
@@ -274,7 +274,7 @@ GEM
       rspec-core (~> 3.5.0)
       rspec-expectations (~> 3.5.0)
       rspec-mocks (~> 3.5.0)
-    rspec-core (3.5.1)
+    rspec-core (3.5.2)
       rspec-support (~> 3.5.0)
     rspec-expectations (3.5.0)
       diff-lcs (>= 1.2.0, < 2.0)
@@ -283,15 +283,15 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.5.0)
     rspec-support (3.5.0)
-    rubocop (0.41.2)
+    rubocop (0.42.0)
       parser (>= 2.3.1.1, < 3.0)
       powerpack (~> 0.1)
       rainbow (>= 1.99.1, < 3.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (~> 1.0, >= 1.0.1)
     ruby-progressbar (1.8.1)
-    ruby_dep (1.3.1)
-    rubypants (0.2.0)
+    ruby_dep (1.4.0)
+    rubypants (0.5.0)
     safe_yaml (1.0.4)
     sass (3.4.22)
     shellany (0.0.1)
@@ -312,11 +312,11 @@ GEM
       ref
     thor (0.19.1)
     tilt (2.0.5)
-    tins (1.6.0)
+    tins (1.12.0)
     trollop (2.1.2)
     typogruby (1.0.18)
       rubypants
-    uglifier (3.0.0)
+    uglifier (3.0.2)
       execjs (>= 0.3.0, < 3)
     unicode-display_width (1.1.0)
     vcr (3.0.3)

data/NEWS.md

@@ -1,5 +1,12 @@
 # Nanoc news
 
+## 4.3 (2016-08-21)
+
+Features:
+
+* Added `Nanoc::Filter.define`, to easily define filters (#895)
+* Made the `nanoc` Gemfile group be auto-required when Nanoc starts (#910) [whitequark]
+
 ## 4.2.4 (2016-07-24)
 
 Fixes:

data/lib/nanoc/base/compilation/filter.rb

@@ -38,6 +38,13 @@ module Nanoc
     extend Nanoc::Int::PluginRegistry::PluginMethods
 
     class << self
+      def define(ident)
+        filter_class = Class.new(::Nanoc::Filter) { identifier(ident) }
+        filter_class.send(:define_method, :run) do |content, params|
+          yield(content, params)
+        end
+      end
+
       # Sets the new type for the filter. The type can be `:binary` (default)
       # or `:text`. The given argument can either be a symbol indicating both
       # “from” and “to” types, or a hash where the only key is the “from” type

data/lib/nanoc/base/contracts_support.rb

@@ -6,9 +6,15 @@ module Nanoc::Int
     class Ignorer
       include Singleton
 
+      # rubocop:disable Style/MethodMissing
       def method_missing(*_args)
         self
       end
+      # rubocop:enable Style/MethodMissing
+
+      def respond_to_missing?(*_args)
+        true
+      end
     end
 
     module DisabledContracts

data/lib/nanoc/base/entities/item_rep.rb

@@ -161,7 +161,6 @@ module Nanoc::Int
     private
 
     def initialize_content
-      # FIXME: Where is :raw?
       @snapshot_contents = { last: @item.content }
     end
   end

data/lib/nanoc/base/repos/data_source.rb

@@ -61,7 +61,7 @@ module Nanoc
     #
     # @return [void]
     def use
-      up if @references == 0
+      up if @references.zero?
       @references += 1
     end
 
@@ -74,7 +74,7 @@ module Nanoc
     # @return [void]
     def unuse
       @references -= 1
-      down if @references == 0
+      down if @references.zero?
     end
 
     # Brings up the connection to the data. Depending on the way data is

data/lib/nanoc/cli.rb

@@ -103,6 +103,11 @@ module Nanoc::CLI
       cmd = load_command_at(cmd_filename)
       add_command(cmd)
     end
+
+    if defined?(Bundler)
+      # Discover external commands through Bundler
+      Bundler.require(:nanoc)
+    end
   end
 
   # Loads site-specific commands.

data/lib/nanoc/cli/commands/compile.rb

@@ -271,7 +271,7 @@ module Nanoc::CLI::Commands
       # @see Listener#start
       def start
         Nanoc::Int::NotificationCenter.on(:compilation_started) do |_rep|
-          if @gc_count % 20 == 0
+          if (@gc_count % 20).zero?
             GC.enable
             GC.start
             GC.disable

data/lib/nanoc/cli/commands/deploy.rb

@@ -62,8 +62,7 @@ module Nanoc::CLI::Commands
 
       target = options.fetch(:target, :default).to_sym
       deploy_configs.fetch(target) do
-        # FIXME: target name is unobvious
-        raise Nanoc::Int::Errors::GenericTrivial, "The site has no deployment configuration for #{target}."
+        raise Nanoc::Int::Errors::GenericTrivial, "The site has no deployment configuration named `#{target}`."
       end
     end
 

data/lib/nanoc/extra/deployers/fog.rb

@@ -84,8 +84,9 @@ module Nanoc::Extra::Deployers
       path     = config[:path]
       cdn_id   = config[:cdn_id]
 
-      # FIXME: confusing error message
-      raise 'The path requires no trailing slash' if path && path[-1, 1] == '/'
+      if path && path.end_with?('/')
+        raise "The path `#{path}` is not supposed to have a trailing slash"
+      end
 
       connection = connect
       directory = get_or_create_bucket(connection, bucket, path)

data/lib/nanoc/extra/filesystem_tools.rb

@@ -55,7 +55,7 @@ module Nanoc::Extra
       all_files_and_dirs_in(dir_name, extra_files).map do |fn|
         case File.ftype(fn)
         when 'link'
-          if 0 == recursion_limit
+          if recursion_limit.zero?
             raise MaxSymlinkDepthExceededError.new(fn)
           else
             absolute_target = resolve_symlink(fn)
@@ -129,7 +129,7 @@ module Nanoc::Extra
 
       case File.ftype(absolute_target)
       when 'link'
-        if 0 == recursion_limit
+        if recursion_limit.zero?
           raise MaxSymlinkDepthExceededError.new(absolute_target)
         else
           resolve_symlink(absolute_target, recursion_limit - 1)

data/lib/nanoc/helpers/blogging.rb

@@ -1,28 +1,7 @@
 module Nanoc::Helpers
-  # 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"`
-  #
-  # * `created_at` - The article's publication timestamp
-  #
-  # 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.
-  #
-  # All "time" item attributes, site configuration attributes or method
-  # parameters can either be a `Time` instance or a string in any format
-  # parseable by `Time.parse`.
-  #
-  # The two main functions are {#sorted_articles} and {#atom_feed}.
+  # @see http://nanoc.ws/doc/reference/helpers/#blogging
   module Blogging
-    # Returns an unsorted list of articles, i.e. items where the `kind`
-    # attribute is set to `"article"`.
-    #
-    # @return [Array] An array containing all articles
+    # @return [Array]
     def articles
       blk = -> { @items.select { |item| item[:kind] == 'article' } }
       if @items.frozen?
@@ -32,11 +11,7 @@ module Nanoc::Helpers
       end
     end
 
-    # 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
+    # @return [Array]
     def sorted_articles
       blk = -> { articles.sort_by { |a| attribute_to_time(a[:created_at]) }.reverse }
 
@@ -190,118 +165,18 @@ module Nanoc::Helpers
       end
     end
 
-    # Returns a string representing the atom feed containing recent articles,
-    # sorted by descending creation date.
-    #
-    # The following attributes must be set on blog articles:
-    #
-    # * `title` - The title of the blog post
-    #
-    # * `created_at` (described above)
-    #
-    # * `kind` (described above) *unless* you are passing an explicit list of
-    #   articles using the `:articles` parameter
-    #
-    # The following attributes can optionally be set on blog articles to
-    # change the behaviour of the Atom feed:
-    #
-    # * `excerpt` - An excerpt of the article, which is usually only a few
-    #   lines long.
-    #
-    # * `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.
-    #
-    # * `custom_url_in_feed` - The url that will be used instead of the
-    #   normal url in the feed (generated from the site's base url + the item
-    #   rep's path). This can be useful when building a link-blog where the
-    #   URL of article is a remote location.
-    #
-    # * `updated_at` - The time when the article was last modified. If this
-    #   attribute is not present, the `created_at` attribute will be used as
-    #   the time when the article was last modified.
-    #
-    # The site configuration will need to have the following attributes:
-    #
-    # * `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 know about the feed title, the feed author
-    # name, and the URI corresponding to the author. These can be specified
-    # using parameters, as attributes in the feed item, or in the site
-    # configuration.
-    #
-    # * `title` - The title of the feed, which is usually also the title of
-    #   the blog.
-    #
-    # * `author_name` - The name of the item's author.
-    #
-    # * `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` - 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
-    #
-    # @example Limiting the number of items in a feed
-    #
-    #   <%= atom_feed :limit => 5 %>
-    #
-    # @option params [Number] :limit (5) The maximum number of articles to
-    #   show
-    #
-    # @option params [Array] :articles (articles) A list of articles to include
-    #   in the feed
-    #
-    # @option params [Boolean] :preserve_order (false) Whether or not the
-    #   ordering of the list of articles should be preserved. If false, the
-    #   articles will be sorted by `created_at`. If true, the list of articles
-    #   will be used as-is, and should have the most recent articles last.
-    #
-    # @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.
-    #
-    # @option params [String] :title The feed's title, if it is not given in
-    #   the item attributes.
-    #
-    # @option params [String] :author_name The name of the feed's author, if
-    #   it is not given in the item attributes.
-    #
-    # @option params [String] :author_uri The URI of the feed's author, if it
-    #   is not given in the item attributes.
-    #
-    # @option params [String] :icon The URI of the feed's icon.
-    #
-    # @option params [String] :logo The URI of the feed's logo.
-    #
-    # @return [String] The generated feed content
+    # @option params [Number] :limit
+    # @option params [Array] :articles
+    # @option params [Boolean] :preserve_order
+    # @option params [Proc] :content_proc
+    # @option params [Proc] :excerpt_proc
+    # @option params [String] :title
+    # @option params [String] :author_name
+    # @option params [String] :author_uri
+    # @option params [String] :icon
+    # @option params [String] :logo
+    #
+    # @return [String]
     def atom_feed(params = {})
       require 'builder'
 
@@ -325,12 +200,7 @@ module Nanoc::Helpers
       builder.build
     end
 
-    # 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 [Nanoc::Int::Item] item The item for which to fetch the URL.
-    #
-    # @return [String] The URL of the given item
+    # @return [String]
     def url_for(item)
       # Check attributes
       if @config[:base_url].nil?
@@ -347,10 +217,7 @@ module Nanoc::Helpers
       end
     end
 
-    # 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
+    # @return [String]
     def feed_url
       # Check attributes
       if @config[:base_url].nil?
@@ -360,15 +227,7 @@ module Nanoc::Helpers
       @item[:feed_url] || @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 and described in his
-    # ["How to make a good ID in Atom" blog post]
-    # (http://web.archive.org/web/20110915110202/http://diveintomark.org/archives/2004/05/28/howto-atom-id).
-    #
-    # @param [Nanoc::Int::Item] item The item for which to create an atom tag
-    #
-    # @return [String] The atom tag for the given item
+    # @return [String]
     def atom_tag_for(item)
       hostname, base_dir = %r{^.+?://([^/]+)(.*)$}.match(@config[:base_url])[1..2]
 
@@ -377,14 +236,9 @@ module Nanoc::Helpers
       'tag:' + hostname + ',' + formatted_date + ':' + base_dir + (item.path || item.identifier.to_s)
     end
 
-    # Converts the given attribute (which can be a string, a Time, a Date or a
-    # DateTime) into a Time. When given a Date instance or a string, the
-    # argument is assumed to be in the local timezone.
-    #
-    # @param [String, Time, Date, DateTime] arg Something that contains time
-    #   information but is not necessarily a Time instance yet
+    # @param [String, Time, Date, DateTime] arg
     #
-    # @return [Time] The Time instance corresponding to the given input
+    # @return [Time]
     def attribute_to_time(arg)
       case arg
       when DateTime

data/lib/nanoc/helpers/breadcrumbs.rb

@@ -1,6 +1,5 @@
 module Nanoc::Helpers
-  # Provides support for breadcrumbs, which allow the user to go up in the
-  # page hierarchy.
+  # @see http://nanoc.ws/doc/reference/helpers/#breadcrumbs
   module Breadcrumbs
     class CannotGetBreadcrumbsForNonLegacyItem < Nanoc::Int::Errors::Generic
       def initialize(identifier)
@@ -8,14 +7,7 @@ module Nanoc::Helpers
       end
     end
 
-    # 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
+    # @return [Array]
     def breadcrumbs_trail
       unless @item.identifier.legacy?
         raise CannotGetBreadcrumbsForNonLegacyItem.new(@item.identifier)

data/lib/nanoc/helpers/capturing.rb

@@ -1,64 +1,14 @@
 module Nanoc::Helpers
-  # 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
-  # that’s not possible when the summary contains eRuby. You could also put
-  # the sidebar inside the actual item, but that’s not very pretty. Instead,
-  # you write the summary on the item itself, but capture it, and print it in
-  # the sidebar layout.
-  #
-  # This helper has been tested with ERB and Haml. Other filters may not work
-  # correctly.
-  #
-  # @example Capturing content for a summary
-  #
-  #   <% 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>
-  #     <%= content_for(@item, :summary) || '(no summary)' %>
-  #   </div>
+  # @see http://nanoc.ws/doc/reference/helpers/#capturing
   module Capturing
     # @overload content_for(name, params = {}, &block)
-    #
-    #   Captures the content inside the block and stores it so that it can be
-    #   referenced later on. The same method, {#content_for}, is used for
-    #   getting the captured content as well as setting it. When capturing,
-    #   the content of the block itself will not be outputted.
-    #
-    #   By default, capturing content with the same name will raise an error if the newly captured
-    #   content differs from the previously captured content. This behavior can be changed by
-    #   providing a different `:existing` option to this method:
-    #
-    #   * `:error`: When content already exists and is not identical, raise an error.
-    #
-    #   * `:overwrite`: Overwrite the previously captured content with the newly captured content.
-    #
-    #   * `:append`: Append the newly captured content to the previously captured content.
-    #
-    #   @param [Symbol, String] name The base name of the attribute into which
-    #     the content should be stored
-    #
-    #   @option params [Symbol] existing Can be either `:error`, `:overwrite`, or `:append`
-    #
+    #   @param [Symbol, String] name
+    #   @option params [Symbol] existing
     #   @return [void]
     #
     # @overload content_for(item, name)
-    #
-    #   Fetches the capture with the given name from the given item and
-    #   returns it.
-    #
-    #   @param [Nanoc::Int::Item] item The item for which to get the capture
-    #
-    #   @param [Symbol, String] name The name of the capture to fetch
-    #
-    #   @return [String] The stored captured content
+    #   @param [Symbol, String] name
+    #   @return [String]
     def content_for(*args, &block)
       if block_given? # Set content
         # Get args
@@ -125,10 +75,7 @@ module Nanoc::Helpers
       end
     end
 
-    # Evaluates the given block and returns its contents. The contents of the
-    # block is not outputted.
-    #
-    # @return [String] The captured result
+    # @return [String]
     def capture(&block)
       # Get erbout so far
       erbout = eval('_erbout', block.binding)

data/lib/nanoc/helpers/child_parent.rb

@@ -1,21 +1,6 @@
 module Nanoc::Helpers
-  # Provides functionality for fetching the children and the parent of a given
-  # item. This works for both full identifiers and legacy identifiers.
+  # @see http://nanoc.ws/doc/reference/helpers/#childparent
   module ChildParent
-    # Returns the parent of the given item.
-    #
-    # For items with legacy identifiers, the parent is the item where the
-    # identifier contains one less component than the identifier of the given
-    # item. For # example, the parent of the “/projects/nanoc/” item is the
-    # “/projects/” item.
-    #
-    # For items with full identifiers, the parent is the item where the
-    # identifier contains one less component than the identifier of the given
-    # item, and ends with any extension. For example, the parent of the
-    # “/projects/nanoc.md” item could be the “/projects.md” item, or the
-    # “/projects.html” item, etc. Note that the parent is ambiguous for items
-    # that have a full identifier; only the first candidate parent item will be
-    # returned.
     def parent_of(item)
       if item.identifier.legacy?
         item.parent
@@ -25,20 +10,6 @@ module Nanoc::Helpers
       end
     end
 
-    # Returns the children of the given item.
-    #
-    # For items with legacy identifiers, the children are the items where the
-    # identifier contains one more component than the identifier of the given
-    # item. For example, the children of the “/projects/” item could be
-    # “/projects/nanoc/” and “/projects/cri/”, but not “/about/” nor
-    # “/projects/nanoc/history/”.
-    #
-    # For items with full identifiers, the children are the item where the
-    # identifier starts with the identifier of the given item, minus the
-    # extension, followed by a slash. For example, the children of the
-    # “/projects.md” item could be the “/projects/nanoc.md” and
-    # “/projects/cri.adoc” items , but not “/about.md” nor
-    # “/projects/nanoc/history.md”.
     def children_of(item)
       if item.identifier.legacy?
         item.children

data/lib/nanoc/helpers/filtering.rb

@@ -1,27 +1,11 @@
 module Nanoc::Helpers
-  # Provides functionality for filtering parts of an item or a layout.
+  # @see http://nanoc.ws/doc/reference/helpers/#filtering
   module Filtering
     require 'nanoc/helpers/capturing'
     include Nanoc::Helpers::Capturing
 
-    # 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] arguments Arguments to pass to the filter
+    # @param [Symbol] filter_name
+    # @param [Hash] arguments
     #
     # @return [void]
     def filter(filter_name, arguments = {}, &block)

data/lib/nanoc/helpers/html_escape.rb

@@ -1,29 +1,12 @@
 module Nanoc::Helpers
-  # Contains functionality for HTML-escaping strings.
+  # @see http://nanoc.ws/doc/reference/helpers/#filtering
   module HTMLEscape
     require 'nanoc/helpers/capturing'
     include Nanoc::Helpers::Capturing
 
-    # Returns the HTML-escaped representation of the given string or the given
-    # block. Only `&`, `<`, `>` and `"` are escaped. When given a block, the
-    # contents of the block will be escaped and appended to the output buffer,
-    # `_erbout`.
+    # @param [String] string
     #
-    # @example Escaping a string
-    #
-    #     h('<br>')
-    #     # => '&lt;br&gt;'
-    #
-    # @example Escaping with a block
-    #
-    #     <% h do %>
-    #       <h1>Hello <em>world</em>!</h1>
-    #     <% end %>
-    #     # The buffer will now contain “&lt;h1&gt;Hello &lt;em&gt;world&lt;/em&gt;!&lt;/h1&gt;”
-    #
-    # @param [String] string The string to escape
-    #
-    # @return [String] The escaped string
+    # @return [String]
     def html_escape(string = nil, &block)
       if block_given?
         # Capture and escape block

data/lib/nanoc/helpers/link_to.rb

@@ -1,46 +1,14 @@
 module Nanoc::Helpers
-  # Contains functions for linking to items and item representations.
+  # @see http://nanoc.ws/doc/reference/helpers/#linkto
   module LinkTo
     require 'nanoc/helpers/html_escape'
     include Nanoc::Helpers::HTMLEscape
 
-    # 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. The HTML-escaping is done
-    # using {Nanoc::Helpers::HTMLEscape#html_escape}.
+    # @param [String] text
     #
-    # @param [String] text The visible link text
+    # @param [Hash] attributes
     #
-    # @param [String, Nanoc::Int::Item, Nanoc::Int::ItemRep] target The path/URL,
-    #   item or item representation that should be linked to
-    #
-    # @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 path
-    #
-    #   link_to('Blog', '/blog/')
-    #   # => '<a href="/blog/">Blog</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 title="My super cool blog" href="/blog/">Blog</a>'
+    # @return [String]
     def link_to(text, target, attributes = {})
       # Find path
       path =
@@ -63,30 +31,11 @@ module Nanoc::Helpers
       "<a #{attributes}href=\"#{h path}\">#{text}</a>"
     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.
+    # @param [String] text
     #
-    # @param [String] text The visible link text
+    # @param [Hash] attributes
     #
-    # @param [String, Nanoc::Int::Item, Nanoc::Int::ItemRep] target The path/URL,
-    #   item or item representation that should be linked to
-    #
-    # @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>'
-    #
-    # @example Linking to the same page
-    #
-    #   link_to_unless_current('This Item', @item)
-    #   # => '<span class="active">This Item</span>'
+    # @return [String]
     def link_to_unless_current(text, target, attributes = {})
       # Find path
       path = target.is_a?(String) ? target : target.path
@@ -99,20 +48,7 @@ module Nanoc::Helpers
       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.
-    #
-    # @param [String, Nanoc::Int::Item, Nanoc::Int::ItemRep] target The path/URL,
-    #   item or item representation to which the relative path should be
-    #   generated
-    #
-    # @return [String] The relative path to the target
-    #
-    # @example
-    #
-    #   # if the current item's path is /foo/bar/
-    #   relative_path_to('/foo/qux/')
-    #   # => '../qux/'
+    # @return [String]
     def relative_path_to(target)
       require 'pathname'
 

data/lib/nanoc/helpers/rendering.rb

@@ -1,78 +1,16 @@
 module Nanoc::Helpers
-  # Provides functionality for rendering layouts as partials.
+  # @see http://nanoc.ws/doc/reference/helpers/#rendering
   module Rendering
     include Nanoc::Helpers::Capturing
 
-    # Renders the given layout. The given layout will be run through the first
-    # matching layout rule.
+    # @param [String] identifier
+    # @param [Hash] other_assigns
     #
-    # When this method is invoked _without_ a block, the return value will be
-    # the rendered layout (a string)  and `_erbout` will not be modified.
+    # @raise [Nanoc::Int::Errors::UnknownLayout]
+    # @raise [Nanoc::Int::Errors::CannotDetermineFilter]
+    # @raise [Nanoc::Int::Errors::UnknownFilter]
     #
-    # When this method is invoked _with_ a block, an empty string will be
-    # returned and the rendered content will be appended to `_erbout`. In this
-    # case, the content of the block will be captured (using the
-    # {Nanoc::Helpers::Capturing} helper) and this content will be made
-    # available with `yield`. In other words, a `yield` inside the partial
-    # will output the content of the block passed to the method.
-    #
-    # (For the curious: the reason why {#render} with a block has this
-    # behaviour of returning an empty string and modifying `_erbout` is
-    # because ERB does not support combining the `<%= ... %>` form with a
-    # method call that takes a block.)
-    #
-    # The assigns (`@item`, `@config`, …) will be available in the partial. It
-    # is also possible to pass custom assigns to the method; these assigns
-    # will be made available as instance variables inside the partial.
-    #
-    # @param [String] identifier The identifier of the layout that should be
-    #   rendered
-    #
-    # @param [Hash] other_assigns A hash containing extra assigns that will be
-    #   made available as instance variables in the partial
-    #
-    # @example Rendering a head and a foot partial around some text
-    #
-    #   <%= render 'head' %> - MIDDLE - <%= render 'foot' %>
-    #   # => "HEAD - MIDDLE - FOOT"
-    #
-    # @example Rendering a head partial with a custom title
-    #
-    #   # The 'head' layout
-    #   <h1><%= @title %></h1>
-    #
-    #   # The item/layout where the partial is rendered
-    #   <%= render 'head', :title => 'Foo' %>
-    #   # => "<h1>Foo</h1>"
-    #
-    # @example Yielding inside a partial
-    #
-    #   # The 'box' partial
-    #   <div class="box">
-    #     <%= yield %>
-    #   </div>
-    #
-    #   # The item/layout where the partial is rendered
-    #   <% render 'box' do %>
-    #     I'm boxy! Luvz!
-    #   <% end %>
-    #
-    #   # Result
-    #   <div class="box">
-    #     I'm boxy! Luvz!
-    #   </div>
-    #
-    # @raise [Nanoc::Int::Errors::UnknownLayout] if the given layout does not
-    #   exist
-    #
-    # @raise [Nanoc::Int::Errors::CannotDetermineFilter] if there is no layout
-    #   rule for the given layout
-    #
-    # @raise [Nanoc::Int::Errors::UnknownFilter] if the layout rule for the given
-    #   layout specifies an unknown filter
-    #
-    # @return [String, nil] The rendered partial, or nil if this method was
-    #   invoked with a block
+    # @return [String, nil]
     def render(identifier, other_assigns = {}, &block)
       # Find layout
       layout = @layouts[identifier]

data/lib/nanoc/helpers/tagging.rb

@@ -1,31 +1,14 @@
 module Nanoc::Helpers
-  # Provides support for managing tags added to items.
-  #
-  # To add tags to items, set the `tags` attribute to an array of tags that
-  # should be applied to the item.
-  #
-  # @example Adding tags to an item
-  #
-  #   tags: [ 'foo', 'bar', 'baz' ]
+  # @see http://nanoc.ws/doc/reference/helpers/#tagging
   module Tagging
     require 'nanoc/helpers/html_escape'
     include Nanoc::Helpers::HTMLEscape
 
-    # Returns a formatted list of tags for the given item as a string. The
-    # tags will be linked using the {#link_for_tag} function; the
-    # HTML-escaping rules for {#link_for_tag} apply here as well.
+    # @param [String] base_url
+    # @param [String] none_text
+    # @param [String] separator
     #
-    # @param [String] base_url The URL to which the tag will be appended
-    #   to construct the link URL. This URL must have a trailing slash. The
-    #   function will return a tags string without tag page link if the param
-    #   is not provided.
-    #
-    # @param [String] none_text The text to display when
-    #   the item has no tags
-    #
-    # @param [String] separator The separator to put between tags
-    #
-    # @return [String] A hyperlinked list of tags for the given item
+    # @return [String]
     def tags_for(item, base_url: nil, none_text: '(none)', separator: ', ')
       if item[:tags].nil? || item[:tags].empty?
         none_text
@@ -34,26 +17,17 @@ module Nanoc::Helpers
       end
     end
 
-    # Find all items with the given tag.
+    # @param [String] tag
     #
-    # @param [String] tag The tag for which to find all items
-    #
-    # @return [Array] All items with the given tag
+    # @return [Array]
     def items_with_tag(tag)
       @items.select { |i| (i[:tags] || []).include?(tag) }
     end
 
-    # Returns a link to to the specified tag. The link is marked up using the
-    # rel-tag microformat. The `href` attribute of the link will be HTML-
-    # escaped, as will the content of the `a` element.
-    #
-    # @param [String] tag The name of the tag, which should consist of letters
-    #   and numbers (no spaces, slashes, or other special characters).
-    #
-    # @param [String] base_url The URL to which the tag will be appended to
-    #   construct the link URL. This URL must have a trailing slash.
+    # @param [String] tag
+    # @param [String] base_url
     #
-    # @return [String] A link for the given tag and the given base URL
+    # @return [String]
     def link_for_tag(tag, base_url)
       %(<a href="#{h base_url}#{h tag}" rel="tag">#{h tag}</a>)
     end

data/lib/nanoc/helpers/text.rb

@@ -1,19 +1,11 @@
 module Nanoc::Helpers
-  # Contains several useful text-related helper functions.
+  # @see http://nanoc.ws/doc/reference/helpers/#text
   module Text
-    # Returns an excerpt for the given string. HTML tags are ignored, so if
-    # you don't want them to turn up, they should be stripped from the string
-    # before passing it to the excerpt function.
+    # @param [String] string
+    # @param [Number] length
+    # @param [String] omission
     #
-    # @param [String] string The string for which to build an excerpt
-    #
-    # @param [Number] length The maximum number of characters
-    #   this excerpt can contain, including the omission.
-    #
-    # @param [String] omission The string to append to the
-    #   excerpt when the excerpt is shorter than the original string
-    #
-    # @return [String] The excerpt of the given string
+    # @return [String]
     def excerptize(string, length: 25, omission: '...')
       if string.length > length
         excerpt_length = [0, length - omission.length].max
@@ -23,11 +15,9 @@ module Nanoc::Helpers
       end
     end
 
-    # Strips all HTML tags out of the given string.
-    #
-    # @param [String] string The string from which to strip all HTML
+    # @param [String] string
     #
-    # @return [String] The given string with all HTML stripped
+    # @return [String]
     def strip_html(string)
       # FIXME: will need something more sophisticated than this, because it sucks
       string.gsub(/<[^>]*(>+|\s*\z)/m, '').strip

data/lib/nanoc/helpers/xml_sitemap.rb

@@ -1,40 +1,10 @@
 module Nanoc::Helpers
-  # Contains functionality for building XML sitemaps that will be crawled by
-  # search engines. See the [Sitemaps protocol site](http://www.sitemaps.org)
-  # for details.
+  # @see http://nanoc.ws/doc/reference/helpers/#xmlsitemap
   module XMLSitemap
-    # Builds an XML sitemap and returns it.
+    # @option params [Array] :items
+    # @option params [Proc] :rep_select
     #
-    # The following attributes can optionally be set on items to change the
-    # behaviour of the sitemap:
-    #
-    # * `changefreq` — The estimated change frequency as defined by the
-    #   Sitemaps protocol
-    #
-    # * `priority` — The item's priority, ranging from 0.0 to 1.0, as defined
-    #   by the Sitemaps protocol
-    #
-    # The sitemap will also include dates on which the items were updated.
-    # These are generated automatically; the way this happens depends on the
-    # used data source (the filesystem data source checks the file mtimes, for
-    # instance).
-    #
-    # The site configuration will need to have the following attributes:
-    #
-    # * `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".
-    #
-    # @example Excluding binary items from the sitemap
-    #
-    #   <%= xml_sitemap :items => @items.reject{ |i| i[:is_hidden] || i.binary? } %>
-    #
-    # @option params [Array] :items A list of items to include in the sitemap
-    #
-    # @option params [Proc] :rep_select A proc to filter reps through. If the
-    #   proc returns true, the rep will be included; otherwise, it will not.
-    #
-    # @return [String] The XML sitemap
+    # @return [String]
     def xml_sitemap(params = {})
       require 'builder'
 

data/lib/nanoc/spec.rb

@@ -47,8 +47,9 @@ module Nanoc
       # @param [Nanoc::ItemWithRepsView] item The item to create a represetation for
       #
       # @param [String] path The path of the `:last` snapshot of this item representation
-      def create_rep(item, path)
-        rep = Nanoc::Int::ItemRep.new(item.unwrap, :default)
+      # @param [Symbol] rep The rep name to create
+      def create_rep(item, path, rep = :default)
+        rep = Nanoc::Int::ItemRep.new(item.unwrap, rep)
         rep.paths[:last] = path
         @reps << rep
         Nanoc::ItemRepView.new(rep, view_context)

data/lib/nanoc/version.rb

@@ -1,4 +1,4 @@
 module Nanoc
   # The current Nanoc version.
-  VERSION = '4.2.4'.freeze
+  VERSION = '4.3.0'.freeze
 end

data/tasks/rubocop.rake

@@ -1,6 +1,6 @@
 require 'rubocop/rake_task'
 
 RuboCop::RakeTask.new(:rubocop) do |task|
-  task.options  = %w( --display-cop-names --format simple )
+  task.options  = %w(--display-cop-names --format simple)
   task.patterns = ['bin/nanoc', 'lib/**/*.rb', 'spec/**/*.rb', 'test/**/*.rb']
 end

data/tasks/test.rake

@@ -4,7 +4,7 @@ require 'coveralls/rake/task'
 
 Coveralls::RakeTask.new
 
-SUBDIRS = %w( * base cli data_sources extra filters helpers ).freeze
+SUBDIRS = %w(* base cli data_sources extra filters helpers).freeze
 
 namespace :test do
   SUBDIRS.each do |dir|

data/test/cli/test_cleaning_stream.rb

@@ -6,9 +6,15 @@ class Nanoc::CLI::CleaningStreamTest < Nanoc::TestCase
       @called_methods = Set.new
     end
 
+    # rubocop:disable Style/MethodMissing
     def method_missing(symbol, *_args)
       @called_methods << symbol
     end
+    # rubocop:enable Style/MethodMissing
+
+    def respond_to_missing?(*_args)
+      true
+    end
   end
 
   def test_forward

data/test/cli/test_error_handler.rb

@@ -48,7 +48,7 @@ class Nanoc::CLI::ErrorHandlerTest < Nanoc::TestCase
 
   def new_error(amount_factor)
     backtrace_generator = lambda do |af|
-      if af == 0
+      if af.zero?
         raise 'finally!'
       else
         backtrace_generator.call(af - 1)

data/test/extra/checking/checks/test_external_links.rb

@@ -52,7 +52,7 @@ class Nanoc::Extra::Checking::Checks::ExternalLinksTest < Nanoc::TestCase
       # Create check
       check = Nanoc::Extra::Checking::Checks::ExternalLinks.create(site)
       def check.request_url_once(url, req_method = Net::HTTP::Head)
-        Net::HTTPResponse.new('1.1', (req_method == Net::HTTP::Head || url.path == '/405') ? '405' : '200', 'okay')
+        Net::HTTPResponse.new('1.1', req_method == Net::HTTP::Head || url.path == '/405' ? '405' : '200', 'okay')
       end
 
       # Test

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: nanoc
 version: !ruby/object:Gem::Version
-  version: 4.2.4
+  version: 4.3.0
 platform: ruby
 authors:
 - Denis Defreyne
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-07-24 00:00:00.000000000 Z
+date: 2016-08-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cri
@@ -86,7 +86,6 @@ extra_rdoc_files:
 - README.md
 - NEWS.md
 files:
-- CONTRIBUTING.md
 - ChangeLog
 - Gemfile
 - Gemfile.lock

data/CONTRIBUTING.md

@@ -1,38 +0,0 @@
-Contributing
-============
-
-Reporting bugs
---------------
-
-If you find a bug in Nanoc, you should report it! Some information that you should include in your bug report is the Nanoc version (`nanoc --version`) and, if relevant, the crash log (`crash.log`).
-
-For details, check the [*bug reporting* section of the development guide](http://nanoc.ws/development/#reporting-bugs).
-
-Contributing code
------------------
-
-Pull requests are appreciated! When submitting a PR, be sure to submit it onto the right branch:
-
-* For bug fixes, use the release branch, e.g. `release-3.6.x`
-* For features, use the `master` branch
-
-When submitting a PR, make sure that your changes have covering tests, that the documentation remains up-to-date and that you retain backwards compatibility.
-
-For details, check the [*contributing code* section of the development guide](http://nanoc.ws/development/#contributing-code).
-
-Contributor Code of Conduct
----------------------------
-
-As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
-
-We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion.
-
-Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
-
-Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.
-
-This code of conduct applies both within project spaces and in public spaces when an individual is representing the project or its community.
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
-
-This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.1.0, available at [http://contributor-covenant.org/version/1/1/0/](http://contributor-covenant.org/version/1/1/0/)