nanoc3 3.1.4 → 3.1.5

data/NEWS.md

@@ -1,5 +1,14 @@
 # nanoc news
 
+## 3.1.5 (2010-08-24)
+
+* Improved `#render` documentation
+* Improved metadata section check so that e.g. raw diffs are handled properly
+* Deprecated using `Nanoc3::Site#initialize` with a non-`"."` argument
+* Added Ruby engine to version string
+* Allowed the `created_at` and `updated_at` attributes used in the `Blogging`
+  helper to be `Date` instances
+
 ## 3.1.4 (2010-07-25)
 
 * Made INT and TERM signals always quit the CLI

data/README.md

@@ -78,6 +78,7 @@ may be interested in the development dependencies:
 * Chris Eppstein
 * Felix Hanley
 * Starr Horne
+* Tuomas Kareinen
 * Nicky Peeters
 * Christian Plessl
 * Šime Ramov

data/lib/nanoc3/base/site.rb

@@ -344,6 +344,9 @@ module Nanoc3
         # Get basic path by applying matching rule
         basic_path = rule.apply_to(rep)
         next if basic_path.nil?
+        if basic_path !~ %r{^/}
+          raise RuntimeError, "The path returned for the #{rep.inspect} item representation, “#{basic_path}”, does not start with a slash. Please ensure that all routing rules return a path that starts with a slash.".make_compatible_with_env
+        end
 
         # Get raw path by prepending output directory
         rep.raw_path = self.config[:output_dir] + basic_path
@@ -364,6 +367,11 @@ module Nanoc3
     # #initialize for details.
     def build_config(dir_or_config_hash)
       if dir_or_config_hash.is_a? String
+        # Check whether it is supported
+        if dir_or_config_hash != '.'
+          warn 'WARNING: Calling Nanoc3::Site.new with a directory that is not the current working directory is not supported. It is recommended to change the directory before calling Nanoc3::Site.new. For example, instead of Nanoc3::Site.new(\'abc\'), use Dir.chdir(\'abc\') { Nanoc3::Site.new(\'.\') }.'
+        end
+
         # Read config from config.yaml in given dir
         config_path = File.join(dir_or_config_hash, 'config.yaml')
         @config = DEFAULT_CONFIG.merge(YAML.load_file(config_path).symbolize_keys)

data/lib/nanoc3/cli/base.rb

@@ -23,12 +23,20 @@ module Nanoc3::CLI
       add_command(Nanoc3::CLI::Commands::View.new)
     end
 
+    # Returns a fully initialised base instance. It is recommended to use this
+    # shared instance than to create new ones, as this will be the instance
+    # that will be used when reading all code from the `lib/` directory.
+    #
+    # @return [Nanoc3::CLI::Base]
     def self.shared_base
       @shared_base ||= Nanoc3::CLI::Base.new
     end
 
-    # Helper function which can be called when a command is executed that
-    # requires a site, such as the compile command.
+    # Asserts that the current working directory contains a site
+    # ({Nanoc3::Site} instance). If no site is present, prints an error
+    # message and exits.
+    #
+    # @return [void]
     def require_site
       if site.nil?
         $stderr.puts 'The current working directory does not seem to be a ' +
@@ -37,7 +45,10 @@ module Nanoc3::CLI
       end
     end
 
-    # Gets the site (Nanoc3::Site) in the current directory and loads its data.
+    # Gets the site ({Nanoc3::Site} instance) in the current directory and
+    # loads its data.
+    #
+    # @return [Nanoc3::Site] The site in the current working directory
     def site
       # Load site if possible
       if File.file?('config.yaml') && (!self.instance_variable_defined?(:@site) || @site.nil?)
@@ -52,7 +63,7 @@ module Nanoc3::CLI
       @site
     end
 
-    # Inherited from ::Cri::Base
+    # @see ::Cri::Base#run
     def run(args)
       # Set exit handler
       [ 'INT', 'TERM' ].each do |signal|
@@ -70,8 +81,12 @@ module Nanoc3::CLI
       exit(1)
     end
 
-    # Prints the given error to stderr. Includes message, possible resolution,
-    # compilation stack, backtrace, etc.
+    # Prints the given error to stderr. Includes message, possible resolution
+    # (see {#resolution_for}), compilation stack, backtrace, etc.
+    #
+    # @param [Error] error The error that should be described
+    #
+    # @return [void]
     def print_error(error)
       $stderr.puts
 
@@ -115,8 +130,12 @@ module Nanoc3::CLI
       $stderr.puts error.backtrace.to_enum(:each_with_index).map { |item, index| "  #{index}. #{item}" }.join("\n")
     end
 
-    # Returns a string containing hints for resolving the given error, or nil
-    # if no resolution can be automatically obtained.
+    # Attempts to find a resolution for the given error, or nil if no
+    # resolution can be automatically obtained.
+    #
+    # @param [Error] error The error to find a resolution for
+    #
+    # @return [String] The resolution for the given error
     def resolution_for(error)
       # FIXME this should probably go somewhere else so that 3rd-party code can add other gem names too
       gem_names = {
@@ -158,6 +177,10 @@ module Nanoc3::CLI
     # Sets the data source's VCS to the VCS with the given name. Does nothing
     # when the site's data source does not support VCSes (i.e. does not
     # implement #vcs=).
+    #
+    # @param [String] vcs_name The name of the VCS that should be used
+    #
+    # @return [void]
     def set_vcs(vcs_name)
       # Skip if not possible
       return if vcs_name.nil? || site.nil?
@@ -178,7 +201,7 @@ module Nanoc3::CLI
       end
     end
 
-    # Returns the list of global option definitionss.
+    # @return [Array] The list of global option definitions
     def global_option_definitions
       [
         {
@@ -208,13 +231,15 @@ module Nanoc3::CLI
       ]
     end
 
+    # @see Cri::Base#handle_option
     def handle_option(option)
       case option
       when :version
         gem_info = defined?(Gem) ? "with RubyGems #{Gem::VERSION}" : "without RubyGems"
+        engine   = defined?(RUBY_ENGINE) ? RUBY_ENGINE : "ruby"
 
         puts "nanoc #{Nanoc3::VERSION} (c) 2007-2010 Denis Defreyne."
-        puts "Ruby #{RUBY_VERSION} (#{RUBY_RELEASE_DATE}) running on #{RUBY_PLATFORM} #{gem_info}"
+        puts "Running #{engine} #{RUBY_VERSION} (#{RUBY_RELEASE_DATE}) on #{RUBY_PLATFORM} #{gem_info}"
         exit 0
       when :verbose
         Nanoc3::CLI::Logger.instance.level = :low

data/lib/nanoc3/cli/logger.rb

@@ -8,6 +8,8 @@ module Nanoc3::CLI
   # feedback in the terminal.
   class Logger
 
+    # Maps actions (`:create`, `:update`, `:identical` and `:skip`) onto their
+    # ANSI color codes.
     ACTION_COLORS = {
       :create         => "\e[1m" + "\e[32m", # bold + green
       :update         => "\e[1m" + "\e[33m", # bold + yellow
@@ -17,12 +19,14 @@ module Nanoc3::CLI
 
     include Singleton
 
-    # The log level, which can be :high, :low or :off (which will log all
-    # messages, only high-priority messages, or no messages at all,
+    # Returns the log level, which can be :high, :low or :off (which will log
+    # all messages, only high-priority messages, or no messages at all,
     # respectively).
+    #
+    # @return [Symbol] The log level
     attr_accessor :level
 
-    # Whether to use color in log messages or not
+    # @return [Boolean] True if color should be used, false otherwise
     attr_accessor :color
     alias_method :color?, :color
 
@@ -40,12 +44,13 @@ module Nanoc3::CLI
 
     # Logs a file-related action.
     #
-    # +level+:: The importance of this action. Can be :high or :low.
+    # @param [:high, :low] level The importance of this action
+    #
+    # @param [:create, :update, :identical] action The kind of file action
     #
-    # +action+:: The kind of file action. Can be :create, :update or
-    #            :identical.
+    # @param [String] name The name of the file the action was performed on
     #
-    # +identifier+:: The identifier of the item the action was performed on.
+    # @return [void]
     def file(level, action, identifier, duration=nil)
       log(
         level,
@@ -61,18 +66,19 @@ module Nanoc3::CLI
 
     # Logs a message.
     #
-    # +level+:: The importance of this message. Can be :high or :low.
+    # @param [:high, :low] level The importance of this message
+    #
+    # @param [String] message The message to be logged
     #
-    # +s+:: The message to be logged.
+    # @param [#puts] io The stream to which the message should be written
     #
-    # +io+:: The IO instance to which the message will be written. Defaults to
-    #        standard output.
-    def log(level, s, io=$stdout)
+    # @return [void]
+    def log(level, message, io=$stdout)
       # Don't log when logging is disabled
       return if @level == :off
 
       # Log when level permits it
-      io.puts(s) if (@level == :low or @level == level)
+      io.puts(message) if (@level == :low or @level == level)
     end
 
   end

data/lib/nanoc3/data_sources/filesystem.rb

@@ -239,7 +239,7 @@ module Nanoc3::DataSources
       data = File.read(content_filename)
 
       # Check presence of metadata section
-      if data[0, 3] != '-'*3 && data[0, 5] != '-'*5
+      if data !~ /\A-{3,5}\s*$/
         return [ {}, data ]
       end
 

data/lib/nanoc3/helpers/blogging.rb

@@ -39,8 +39,7 @@ module Nanoc3::Helpers
     def sorted_articles
       require 'time'
       articles.sort_by do |a|
-        time = a[:created_at]
-        time.is_a?(String) ? Time.parse(time) : time
+        attribute_to_time(a[:created_at])
       end.reverse
     end
 
@@ -183,8 +182,7 @@ module Nanoc3::Helpers
 
       # 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
+        attribute_to_time(a[:created_at])
       end.reverse.first(limit)
 
       # Get most recent article
@@ -204,8 +202,7 @@ module Nanoc3::Helpers
         xml.title   title
 
         # Add date
-        time = last_article[:created_at]
-        xml.updated((time.is_a?(String) ? Time.parse(time) : time).to_iso8601_time)
+        xml.updated(attribute_to_time(last_article[:created_at]).to_iso8601_time)
 
         # Add links
         xml.link(:rel => 'alternate', :href => root_url)
@@ -229,10 +226,8 @@ module Nanoc3::Helpers
             xml.title     a[:title], :type => 'html'
 
             # Add dates
-            create_time = a[:created_at]
-            update_time = a[:updated_at] || a[:created_at]
-            xml.published((create_time.is_a?(String) ? Time.parse(create_time) : create_time).to_iso8601_time)
-            xml.updated(  (update_time.is_a?(String) ? Time.parse(update_time) : update_time).to_iso8601_time)
+            xml.published attribute_to_time(a[:created_at]).to_iso8601_time
+            xml.updated   attribute_to_time(a[:updated_at] || a[:created_at]).to_iso8601_time
 
             # Add link
             xml.link(:rel => 'alternate', :href => url)
@@ -297,12 +292,24 @@ module Nanoc3::Helpers
 
       hostname, base_dir = %r{^.+?://([^/]+)(.*)$}.match(@site.config[:base_url])[1..2]
 
-      time = item[:created_at]
-      formatted_date = (time.is_a?(String) ? Time.parse(time) : time).to_iso8601_date
+      formatted_date = attribute_to_time(item[:created_at]).to_iso8601_date
 
       'tag:' + hostname + ',' + formatted_date + ':' + base_dir + (item.path || item.identifier)
     end
 
+    # Converts the given attribute (which can be a string, a Time or a Date)
+    # into a Time.
+    #
+    # @param [String, Time, Date] time Something that contains time
+    #   information but is not necessarily a Time instance yet
+    #
+    # @return [Time] The Time instance corresponding to the given input
+    def attribute_to_time(time)
+      time = Time.local(time.year, time.month, time.day) if time.is_a?(Date)
+      time = Time.parse(time) if time.is_a?(String)
+      time
+    end
+
   end
 
 end

data/lib/nanoc3/helpers/rendering.rb

@@ -7,13 +7,24 @@ module Nanoc3::Helpers
 
     include Nanoc3::Helpers::Capturing
 
-    # Returns a string containing the rendered given layout.
+    # Returns a string containing the rendered given layout. The given layout
+    # will first be run through the matching layout rule.
+    #
+    # The assigns (`@item`, `@config`, …) will not be available in the
+    # partial, but it is possible to pass custom assigns to the method. These
+    # assigns will be made available as instance variables inside the partial.
+    #
+    # The method can also take a block. In this case, the content of the block
+    # will be captured (using the {Nanoc3::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.
     #
     # @param [String] identifier The identifier of the layout that should be
-    # rendered
+    #   rendered
     #
     # @param [Hash] other_assigns A hash containing assigns that will be made
-    # available as instance variables in the partial
+    #   available as instance variables in the partial
     #
     # @example Rendering a head and a foot partial around some text
     #
@@ -29,8 +40,20 @@ module Nanoc3::Helpers
     #   <%= 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 %>
+    #
     # @raise [Nanoc3::Errors::UnknownLayout] if the given layout does not
-    # exist
+    #   exist
     #
     # @return [String] The rendered partial
     def render(identifier, other_assigns={}, &block)

data/lib/nanoc3.rb

@@ -3,7 +3,7 @@
 module Nanoc3
 
   # The current nanoc version.
-  VERSION = '3.1.4'
+  VERSION = '3.1.5'
 
 end
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: nanoc3
 version: !ruby/object:Gem::Version 
-  hash: 11
+  hash: 9
   prerelease: false
   segments: 
   - 3
   - 1
-  - 4
-  version: 3.1.4
+  - 5
+  version: 3.1.5
 platform: ruby
 authors: 
 - Denis Defreyne
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-07-25 00:00:00 +02:00
+date: 2010-08-24 00:00:00 +02:00
 default_executable: nanoc3
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -47,7 +47,6 @@ extra_rdoc_files:
 - NEWS.md
 files: 
 - ChangeLog
-- Gemfile
 - LICENSE
 - NEWS.md
 - Rakefile

data/Gemfile

@@ -1,31 +0,0 @@
-source "http://rubygems.org"
-
-gem "cri"
-
-group :development do
-  gem "minitest"
-  gem "mocha"
-  gem "yard"
-end
-
-group :extra do
-  gem "adsf"
-  gem "bluecloth"
-  gem "builder"
-  gem "coderay"
-  gem "erubis"
-  gem "haml"
-  gem "kramdown"
-  gem "less"
-  gem "markaby"
-  gem "maruku"
-  gem "mime-types"
-  gem "nokogiri"
-  gem "rack"
-  gem "rainpress"
-  gem "rdiscount"
-  gem "rdoc"
-  gem "RedCloth"
-  gem "rubypants"
-  gem "w3c_validators"
-end