RubyGems - mint - Versions diffs - 0.2.7 → 0.2.8 - Mend

mint 0.2.7 → 0.2.8

Files changed (11) hide show

data/README.md CHANGED

@@ -73,8 +73,8 @@ Notes:
 1. If you specify a template name here, Mint will search its paths in order (see **The Mint Path** for more details) for a template with that name. A template file looks like the following:
-      ${MINT_PATH}/templates/template_name/style.css
-      ${MINT_PATH}/templates/template_name/layout.haml
+      MINT_PATH/templates/template_name/style.css
+      MINT_PATH/templates/template_name/layout.haml
 2. If you specify a template name that is also the name of an existing file in your working directory, Mint will use the file and not look for a template. (It is unlikely you'll have an extension-less file named 'normal' or 'default' in your working directory, so don't worry about this edge case.) If you do specify an existing file, the path/file will be resolved from the directory where you're calling Mint (the 'working directory'). To use Mint this way (and I don't see this as more than a temporary solution) you'll probably want to call Mint from within your source's directory. Alternatively, you can use [`Dir.chdir`][Dir::chdir method] for the same effect.
@@ -137,13 +137,13 @@ Templates are rendered in the context of the document they are "about", so Mint
 In Mint layouts, Ruby calls are sparse but necessary.
-If you're designing a layout, you need to indicate where Mint should place your content. For that simple reason, raw Html files cannot be layouts. Instead, if you want to use Html templates, you should use the Erb format. These files are essentially Html with the possibility for Ruby calls. You can even use the .html extension for your files. Just code the dynamic portion using Erb syntax.
+If you're designing a layout, you need to indicate where Mint should place your content. For that simple reason, raw HTML files cannot be layouts. Instead, if you want to use HTML templates, you should use the ERB format. These files are essentially HTML with the possibility for Ruby calls. You can even use the .html extension for your files. Just code the dynamic portion using ERB syntax.
 Inside your template, use the `content` method to place your source's content.
 You will want to point to your document's stylesheet (via a relative URL) from within your layout, usually in the `<head/>` element. Use the `stylesheet` method.
-So if you're writing your layout using Erb, the template might look like this:
+So if you're writing your layout using ERB, the template might look like this:
     <!doctype html>
     <html>
@@ -170,13 +170,13 @@ The same layout in Haml would be:
 ### Style your content ###
-You can build stylesheets using [Css][], [Sass/Scss][] or [Less][]. They will
+You can build stylesheets using [CSS][], [SASS/SCSS][] or [Less][]. They will
 always be compiled. They will only be copied, though, if you specify a style
 destination.
 [Tilt templates]: http://github.com/rtomayko/tilt/blob/master/TEMPLATES.md "A listing of all templates supported by Tilt."
-[Css]: http://en.wikipedia.org/wiki/Cascading_Style_Sheets
-[Sass/Scss]: http://sass-lang.com/
+[CSS]: http://en.wikipedia.org/wiki/Cascading_Style_Sheets
+[SASS/SCSS]: http://sass-lang.com/
 [Less]: http://lesscss.org/
 Mint comes preloaded with several styles and layouts.
@@ -212,8 +212,8 @@ The default Mint path (in order) is:
 Templates should be in a directory named templates. Inside this directory, there should be a subdirectory for each template:
-- `${MINT_PATH}/templates/normal/style.sass`
-- `${MINT_PATH}/templates/normal/layout.haml`
+- `MINT_PATH/templates/normal/style.sass`
+- `MINT_PATH/templates/normal/layout.haml`
 Normally a style will go best with its layout complement. However, layouts and styles can be mixed and matched at your discretion. This is especially true where you are primarily customizing DOM elements with your stylesheet instead of targeting specific IDs or classes you're expecting to find. (In other words, this works best when your stylesheet focuses on modifying typography and not page layout.)
@@ -339,7 +339,7 @@ This section documents features that do not yet exist, but that I would like to
 ### Composed styles ###
-Not everyone wants to code an entire stylesheet every time he wants a new look. In fact, the most common use case for stylesheets is probably tweaking typography. For this reason (and to make this tool as accessible as possible), I want to implement a feature where you can select one stylesheet as a base and implement tweaks on top of that file, using a Yaml-based DSL. Of course Css makes this easy enough, but I want to implement this feature in such a way that it is easy and intuitive for everyone.
+Not everyone wants to code an entire stylesheet every time he wants a new look. In fact, the most common use case for stylesheets is probably tweaking typography. For this reason (and to make this tool as accessible as possible), I want to implement a feature where you can select one stylesheet as a base and implement tweaks on top of that file, using a Yaml-based DSL. Of course CSS makes this easy enough, but I want to implement this feature in such a way that it is easy and intuitive for everyone.
 ### Packages ###

data/lib/mint/commandline.rb CHANGED

@@ -4,15 +4,27 @@ require 'optparse'
 module Mint
   module CommandLine
-    # A map of all options that mint allows by default. Mint will
+    # Commandline-related helper methods
+    # Returns a map of all options that mint allows by default. Mint will
     # consume these arguments, with optional parameters, from
     # the commandline. (All other arguments are taken to be
     # filenames.)
+    #
+    # @return [Hash] a structured set of options that the commandline
+    #   executable accepts
     def self.options
       options_file = "../../../#{Mint.files[:syntax]}"
       YAML.load_file File.expand_path(options_file, __FILE__)
     end
+    # Yields each commandline option specified by options_metadata as
+    # a key/value pair to a block. If the option does not take a param, the value
+    # will be specified as true.
+    #
+    # @param [Hash, #[]] options_metadata a structured set of options that the executable
+    #   can use to parse commandline configuration options
+    # @return [OptionParser] an object that will parse ARGV when called
     def self.parser(options_metadata=Mint::CommandLine.options)
       optparse = OptionParser.new do |opts|
         opts.banner = 'Usage: mint [command] files [options]'
@@ -37,6 +49,13 @@ module Mint
       end
     end
+    # Returns a hash of all active options specified by file (for all scopes).
+    # That is, if you specify file as 'config.yaml', this will return the aggregate
+    # of all config.yaml-specified options in the Mint path, where more local
+    # members of the path take precedence over more global ones.
+    #
+    # @param [String] file a filename pointing to a Mint configuration file
+    # @return [Hash] a structured set of configuration options
     def self.configuration(file=Mint.files[:config])
       return nil unless file
       config_file = Pathname.new file
@@ -53,29 +72,49 @@ module Mint
       Helpers.symbolize_keys configuration
     end
+    # Returns all configuration options (as specified by the aggregate
+    # of all config files), along with opts, where opts take precedence.
+    #
+    # @param [Hash] additional options to add to the current configuration
+    # @return [Hash] a structured set of configuration options with opts
+    #   overriding any options from config files
     def self.configuration_with(opts)
       configuration.merge opts
     end
+    # Mint built-in commands
+    # Prints a help banner
+    #
+    # @param [String, #to_s] message a message to output
+    # @return [void]
     def self.help(message)
       puts message
     end
-    # Install the listed file to the scope listed, using
-    # local as the default scope.
-    def self.install(file, commandline_options)
+    # @param [File] file the file to install to the appropriate Mint directory
+    # @param [Hash] commandline_options a structured set of options, including
+    #   a scope label that the method will use to choose the appropriate
+    #   installation directory
+    # @return [void]
+    def self.install(file, commandline_options={})
       commandline_options[:local] = true
       scope = [:global, :user, :local].
         select {|e| commandline_options[e] }.
         first
-      directory = path_for_scope(scope)
+      directory = Mint.path_for_scope(scope)
       FileUtils.copy file, directory
     end
-    # If we get the edit command, will retrieve appropriate file
-    # (probably a Mint template) and shell out that file to
-    # the user's favorite editor.
+    # Retrieve named template file (probably a built-in or installed
+    # template) and shell out that file to the user's favorite editor.
+    #
+    # @param [String] name the name of a layout or style to edit
+    # @param [Hash] commandline_options a structured set of options, including
+    #   a layout or style flag that the method will use to choose the appropriate
+    #   file to edit
+    # @return [void]
     def self.edit(name, commandline_options)
       layout = commandline_options[:layout]
       style = commandline_options[:style]
@@ -94,6 +133,13 @@ module Mint
       system "#{editor} #{file}"
     end
+    # Updates configuration options persistently in the appropriate scope,
+    # which defaults to local.
+    #
+    # @param [Hash] opts a structured set of options to set on Mint at the specified
+    #   scope
+    # @param [Symbol] scope the scope at which to apply the set of options
+    # @return [void]
     def self.configure(opts, scope=:local)
       config_directory = Mint.path_for_scope(scope, true)
       config_file = config_directory + Mint.files[:config]
@@ -101,8 +147,15 @@ module Mint
       Helpers.update_yaml opts, config_file
     end
-    # Try to set a config option (at the specified scope) per
+    # Tries to set a config option (at the specified scope) per
     # the user's command.
+    #
+    # @param key the key to set
+    # @param value the value to set key to
+    # @param [Hash, #[]] commandline_options a structured set of options, including
+    #   a scope label that the method will use to choose the appropriate
+    #   scope
+    # @return [void]
     def self.set(key, value, commandline_options)
       commandline_options[:local] = true
       scope = [:global, :user, :local].
@@ -112,18 +165,25 @@ module Mint
       configure({ key => value }, scope)
     end
-    # Display all active configurations, where local
+    # Displays the sum of all active configurations, where local
     # configurations override global ones.
+    #
+    # @return [void]
     def self.config
       puts YAML.dump(configuration)
     end
     # Renders and writes to file all resources described by a document.
-    # Specifically: it renders itself (inside of its own layout) and then
-    # renders its style. This method will overwrite any existing content
-    # in a document's destination files. The `render_style` option
-    # provides an easy way to stop Mint from rendering a style, even
-    # if the document's style is not nil.
+    # Specifically: it publishes a document, using the document's accessors
+    # to determine file placement and naming, and then renders its style.
+    # This method will overwrite any existing content in a document's destination
+    # files. The `render_style` option provides an easy way to stop Mint from
+    # rendering a style, even if the document's style is not nil.
+    #
+    # @param [Array, #each] files a group of filenames
+    # @param [Hash, #[]] commandline_options a structured set of configuration options
+    #   that will guide Mint.publish!
+    # @return [void]
     def self.mint(files, commandline_options)
       documents = []
       options = configuration_with commandline_options
@@ -140,4 +200,3 @@ module Mint
     end
   end
 end

data/lib/mint/css.rb CHANGED

@@ -4,8 +4,15 @@ module Mint
       'container'
     end
-    # Mappings from "DSL" to actual CSS. This is not yet implemented, but
-    # the plan is to translate this into something like:
+    # Maps a "DSL" onto actual CSS. This is not yet implemented, but
+    # the plan is to translate this ...
+    #
+    # ---
+    # Font: Helvetica
+    # Margin: 1 in
+    # Line spacing: 1.25
+    #
+    # ... into something like:
     #
     # #container {
     #   font: (value specified and cleaned up)

data/lib/mint/document.rb CHANGED

@@ -4,24 +4,26 @@ require 'mint/style'
 module Mint
   class Document < Resource
-    # The following provide reader/accessor methods for the objects's
-    # important attributes. Each implicit reader is paired with an
-    # explicit assignment method that processes a variety of input to a
-    # standardized state.
-    # When you set content, you are giving the document a renderer based
-    # on the content file and are processing the templated content into
-    # Html, which you can then access using via the content reader.
-    attr_reader :content
+    # Implicit readers are paired with explicit accessors. This
+    # allows for processing variables before storing them.
+    attr_reader :content, :layout, :style
+    # Passes content through a renderer before assigning it to be
+    # the Document's content
+    #
+    # @param [File, #read, #basename] content the content to be rendered
+    #   from a templating language into HTML
+    # @return [void]
     def content=(content)
       @renderer = Mint.renderer content
       @content = @renderer.render
     end
-    # The explicit assignment method allows you to pass the document an existing
-    # layout or the name of a layout template in the Mint path or an
-    # existing layout file.
-    attr_reader :layout
+    # Sets layout to an existing Layout object or looks it up by name
+    #
+    # @param [String, Layout, #render] layout a Layout object or name
+    #   of a layout to be looked up
+    # @return [void]
     def layout=(layout)
       @layout =
         if layout.respond_to? :render
@@ -34,10 +36,11 @@ module Mint
       abort "Template '#{layout}' does not exist."
     end
-    # The explicit assignment method allows you to pass the document an existing
-    # style or the name of a style template in the Mint path or an
-    # existing style file.
-    attr_reader :style
+    # Sets layout to an existing Style object or looks it up by name
+    #
+    # @param [String, Style, #render] layout a Layout object or name
+    #   of a layout to be looked up
+    # @return [void]
     def style=(style)
       @style =
         if style.respond_to? :render
@@ -50,23 +53,35 @@ module Mint
       abort "Template '#{style}' does not exist."
     end
+    # Explanation of style_destination:
+    #
     # I'm going to maintain a document's official style_destination
     # outside of its style object. If a document has no
     # style_destination defined when it needs one, the document will
-    # use the style's source directory. This happens lazily via
-    # virtual attributes like #style_destination_file, etc.
-    # This eliminates edge cases (like styles we don't want to move
-    # anywhere) nicely and lets us maintain document-specific information
-    # separately. (Without this separation, funky things happen when
+    # use the original style's source directory.
+    #
+    # This decision eliminates edge cases, including the case where
+    # we want to generate, but not move, a document's style. It also
+    # lets us keep style information separate from document-specific
+    # information. (Without this separation, funky things happen when
     # you assign a new style template to an existing document -- if
     # you had specified a custom style_destination before changing
-    # the template, that custom destination would be overridden.
+    # the template, that custom destination would be overridden.)
+    #
+    # The style_destination attribute is lazy. It's exposed via
+    # virtual attributes like #style_destination_file.
     attr_reader :style_destination
+    #
+    # @param [String] style_destination the subdirectory into
+    #   which styles will be rendered or copied
+    # @return [void]
     def style_destination=(style_destination)
       @style_destination = style_destination
     end
+    # Exposes style_destination as a Pathname object.
+    #
+    # @return [Pathname]
     def style_destination_file_path
       if style_destination
         path = Pathname.new style_destination
@@ -78,18 +93,31 @@ module Mint
       end
     end
+    # Exposes style_destination as a String.
+    #
+    # @return [String]
     def style_destination_file
       style_destination_file_path.to_s
     end
+    # Exposes style_destination directory as a Pathname object.
+    #
+    # @return [Pathname]
     def style_destination_directory_path
       style_destination_file_path.dirname
     end
+    # Exposes style_destination directory as a String.
+    #
+    # @return [String]
     def style_destination_directory
       style_destination_directory_path.to_s
     end
+    # Overrides layout and style settings with named template.
+    #
+    # @param [String] template the name of the template to set as
+    #   layout and string
     def template=(template)
       if template
         self.layout = template
@@ -97,6 +125,9 @@ module Mint
       end
     end
+    # Creates a new Mint Document object. Can be block initialized.
+    # Accepts source and options. Block initialization occurs after
+    # all defaults are set, so not all options must be specified.
     def initialize(source, opts={})
       options = Mint.default_options.merge opts
@@ -120,20 +151,20 @@ module Mint
       yield self if block_given?
     end
-    # Render content in the context of layout
+    # Renders content in the context of layout and returns as a String.
     def render(args={})
       layout.render self, args
     end
-    # Write all rendered content where a) possible, b) required,
-    # and c) specified
+    # Writes all rendered content where a) possible, b) required,
+    # and c) specified. Outputs to specified file.
     def publish!(render_style=true)
       FileUtils.mkdir_p self.destination_directory
       File.open(self.destination_file, 'w+') do |f|
         f << self.render
       end
-      # Only render style if a) it's specified by the options path and
+      # Only renders style if a) it's specified by the options path and
       # b) it actually needs rendering (i.e., it's in template form and
       # not raw, browser-parseable CSS) or it if it doesn't need
       # rendering but there is an explicit style_destination.

data/lib/mint/exceptions.rb CHANGED

@@ -1,3 +1,5 @@
 module Mint
+  # Indicates that a named template is not located anywhere
+  # in the Mint path.
   class TemplateNotFoundException < Exception; end
 end

data/lib/mint/helpers.rb CHANGED

@@ -3,6 +3,11 @@ require 'yaml'
 module Mint
   module Helpers
+    # Transforms a String into a URL-ready slug. Properly handles
+    # ampersands, non-alphanumeric characters, extra hyphens and spaces.
+    #
+    # @param [String, #to_s] obj an object to be turned into a slug
+    # @return [String] a URL-ready slug
     def self.slugize(obj)
       obj.to_s.downcase.
         gsub(/&/, 'and').
@@ -11,10 +16,18 @@ module Mint
         gsub(/[-]+/, '-')
     end
+    # Transforms a potentially hyphenated String into a symbol name.
+    #
+    # @param [String, #to_s] obj an object to be turned into a symbol name
+    # @return [Symbol] a symbol representation of obj
     def self.symbolize(obj)
       slugize(obj).gsub(/-/, '_').to_sym
     end
+    # Transforms a String or Pathname into a fully expanded Pathname.
+    #
+    # @param [String, Pathname] str_or_path a path to be expanded
+    # @return [Pathname] an expanded representation of str_or_path
     def self.pathize(str_or_path)
       case str_or_path
       when String
@@ -24,6 +37,10 @@ module Mint
       end.expand_path
     end
+    # Recursively transforms all keys in a Hash into Symbols.
+    #
+    # @param [Hash, #[]] map a potentially nested Hash containing symbolizable keys
+    # @return [Hash] a version of map where all keys are symbols
     def self.symbolize_keys(map)
       map.reduce(Hash.new) do |syms,(k,v)|
         syms[k.to_sym] =
@@ -39,13 +56,24 @@ module Mint
     # Returns the relative path to dir1 from dir2. If dir1 and dir2
     # have no directories in common besides /, will return the
-    # absolute directory of dir1. Right now, assumes no symlinks
+    # absolute directory of dir1. Assumes no symlinks.
+    #
+    # @param [String, Pathname] dir1 the target directory
+    # @param [String, Pathname] dir2 the starting directory
+    # @return [Pathname] the relative path to dir1 from dir2, or an absolute
+    #   path if they have no parent directories other than / in common
     def self.normalize_path(dir1, dir2)
       path1, path2 = [dir1, dir2].map {|d| pathize d }
       root1, root2 = [path1, path2].map {|p| p.each_filename.first }
       root1 == root2 ? path1.relative_path_from(path2) : path1
     end
+    # Reads Yaml options from file. Updates values with new_opts. Writes
+    # merged data back to the same file, overwriting previous data.
+    #
+    # @param [Hash, #[]] new_opts a set of options to add to the Yaml file
+    # @param [Pathname, #exist] file a file to read from and write to
+    # @return [void]
     def self.update_yaml(new_opts, file)
       curr_opts = file.exist? ? YAML.load_file(file) : {}

data/lib/mint/layout.rb CHANGED

@@ -1,10 +1,12 @@
 require 'mint/resource'
 module Mint
-  # Layout describes a resource whose type is `:layout`. Beyond its type,
-  # it is a simple resource. However, its type helps decide which template
-  # file to use when a template name is specified.
   class Layout < Resource
+    # Creates a new Layout object using a mandatory source file
+    # and optional configuration options.
+    #
+    # @param [String] source the absolute or relative file path
+    # @param [Hash, #[]] opts layout options
     def initialize(source, opts=Mint.default_options)
       super(source, opts)
       self.type = :layout

data/lib/mint/mint.rb CHANGED

@@ -3,8 +3,6 @@ require 'fileutils'
 require 'yaml'
 require 'tilt'
-require 'mint/exceptions'
 module Mint
   # Assume that someone using an Html template has formatted it
   # in Erb and that a Css stylesheet will pass untouched through
@@ -12,14 +10,18 @@ module Mint
   Tilt.register Tilt::ERBTemplate, :html
   Tilt.register Tilt::ScssTemplate, :css
+  # @return [String] the Mint root path name
   def self.root
     (Pathname.new(__FILE__).realpath.dirname + '../..').to_s
   end
-  # Return the an array with the Mint template path. Will first look
+  # Returns an array with the Mint template path. Will first look
   # for MINT_PATH environment variable. Otherwise will use smart defaults.
   # Either way, earlier/higher paths take precedence. And is considered to
   # be the directory for "local" config options, templates, etc.
+  #
+  # @param [Boolean] as_path if as_path is true, will return Pathname objects
+  # @return [String] the Mint path as a String or Pathname
   def self.path(as_path=false)
     mint_path = ENV['MINT_PATH'] ||
       "#{Dir.getwd}/.mint:~/.mint:#{Mint.root}"
@@ -27,11 +29,16 @@ module Mint
     as_path ? paths.map {|p| Pathname.new(p).expand_path } : paths
   end
+  # Returns the part of Mint.path relevant to scope.
   # I want to refactor this so that Mint.path is always a Hash...
   # should take care of this in the Mint.path=() method.
   # Right now, this is a hack. It assumes a sane MINT_PATH, where the
   # first entry is most local, the second is user-level,
   # and the last entry is most global.
+  #
+  # @param [Symbol] scope the scope we want to find the path for
+  # @param [Boolean] as_path if as_path is true, will return Pathname object
+  # @return [String] the Mint path for +scope+ as a String or Pathname
   def self.path_for_scope(scope=:local, as_path=false)
     case Mint.path
     when Array
@@ -44,7 +51,7 @@ module Mint
     end
   end
-  # Returns a hash with key Mint directories
+  # @return [Hash] key Mint directories
   def self.directories
     {
       templates: 'templates',
@@ -52,7 +59,7 @@ module Mint
     }
   end
-  # Returns a hash with key Mint files
+  # @return [Hash] key Mint files
   def self.files
     {
       syntax: directories[:config] + '/syntax.yaml',
@@ -60,6 +67,7 @@ module Mint
     }
   end
+  # @return [Hash] last-resort options for creating Mint documents.
   def self.default_options
     {
       # Do not set default `template`--will override style and
@@ -71,19 +79,18 @@ module Mint
     }
   end
-  # Returns a list of all file extensions that Tilt will render
+  # @return [Array] all file extensions that Tilt will render
   def self.formats
     Tilt.mappings.keys
   end
-  # Registered Css formats, for source -> destination
-  # name guessing/conversion only.
+  # @return [Array] CSS formats, for source -> destination
+  #   name guessing/conversion only.
   def self.css_formats
-    css_formats = ['css', 'sass', 'scss', 'less']
+    ['css', 'sass', 'scss', 'less']
   end
-  # Lists the full path for each known template in the
-  # Mint path
+  # @return [Array] the full path for each known template in the Mint path
   def self.templates
     templates_dir = Mint.directories[:templates]
@@ -104,19 +111,29 @@ module Mint
   # referring to the file ~/.mint/templates/normal/layout.erb.
   # Adding :style as a second argument returns
   # ~/.mint/templates/normal/style.css.
+  #
+  # @param [String, File, #to_s] name_or_file a name or template file
+  #   to look up
+  # @param [Symbol] type the resource type to look up
+  # @return [File] the named, typed template file
   def self.lookup_template(name_or_file, type=:layout)
     name = name_or_file.to_s
     File.exist?(name) ? name : find_template(name, type)
   end
   # Finds a template named `name` in the Mint path. If `type` is :layout,
-  # will look for `${MINT_PATH}/templates/layout.*`. If it is :style, will
-  # look for `${MINT_PATH}/templates/template_name/style.*`. Mint assumes
+  # will look for `MINT_PATH/templates/layout.*`. If it is :style, will
+  # look for `MINT_PATH/templates/template_name/style.*`. Mint assumes
   # that a named template will hold only one layout and one style template.
   # It does not know how to decide between style.css and style.less, for
   # example. For predictable results, only include one template file
   # called `layout.*` in the `template_name` directory. Returns nil if
   # it cannot find a template.
+  #
+  # @param [String, #to_s] name the name of a template to find
+  # @param [Symbol] type the resource type to find
+  #
+  # @return [File] the named, typed template file
   def self.find_template(name, type)
     templates_dir = Mint.directories[:templates]
@@ -131,8 +148,11 @@ module Mint
     template
   end
-  # A non-rigourous check to see if the file is somewhere on the
+  # Checks (non-rigorously) to see if the file is somewhere on the
   # MINT_PATH
+  #
+  # @param [String, File, #to_s] file the file to look up
+  # @return [Boolean] true if template file is found in Mint path
   def self.template?(file)
     paths = Mint.path.map {|f| File.expand_path f }
     file_path = Pathname.new(file)
@@ -142,6 +162,9 @@ module Mint
   # Guesses an appropriate name for the resource output file based on
   # its source file's base name
+  #
+  # @param [String] name source file name
+  # @return [String] probably output file name
   def self.guess_name_from(name)
     name = Pathname(name).basename if name
     css = Mint.css_formats.join '|'
@@ -152,10 +175,16 @@ module Mint
   # Transforms a path into a template that will render the file specified
   # at that path
+  #
+  # @param [Path, File, String, #to_s] path the file to render
   def self.renderer(path)
     Tilt.new path.to_s, :smart => true, :ugly => true
   end
+  # Publishes a Document object according to its internal specifications.
+  #
+  # @param [Document] document a Mint document
+  # @return [void]
   def self.publish!(document)
     document.publish!
   end

data/lib/mint/style.rb CHANGED

@@ -1,10 +1,12 @@
 require 'mint/resource'
 module Mint
-  # Style describes a resource whose type is `:style`. Beyond its type,
-  # it is a simple resource. However, its type helps decide which template
-  # file to use when a template name is specified.
   class Style < Resource
+    # Creates a new Layout object using a mandatory source file
+    # and optional configuration options.
+    #
+    # @param [String] source the absolute or relative file path
+    # @param [Hash, #[]] opts style options
     def initialize(source, opts=Mint.default_options)
       super(source, opts)
       self.type = :style
@@ -12,8 +14,8 @@ module Mint
       # We want to render final stylesheet to the /css subdirectory if
       # an output directory is not specified and we are dealing with
       # a named template (not a local file). If we don't do this, the rendered
-      # Css file might be picked up next time we look for a named template
-      # in this directory, and the (correct) Sass file won't be picked up.
+      # CSS file might be picked up next time we look for a named template
+      # in this directory, and the (correct) SASS file won't be picked up.
       # However, if a destination directory is already specified, we
       # leave it alone.
       if Mint.template?(self.source_directory) and rendered?
@@ -21,6 +23,17 @@ module Mint
       end
     end
+    # Determines whether a Style object is supposed to be rendered.
+    #
+    # @return [Boolean] whether or not style should be rendered
+    def rendered?
+      source_file_path.extname !~ /\.css$/
+    end
+    # Renders a Style object if necessary. Otherwise, returns the contents
+    # of its source file.
+    #
+    # @return [String] a rendered stylesheet
     def render
       if rendered?
         super
@@ -28,9 +41,5 @@ module Mint
         File.read source
       end
     end
-    def rendered?
-      source_file_path.extname !~ /\.css$/
-    end
   end
 end

data/lib/mint/version.rb CHANGED

@@ -1,3 +1,3 @@
 module Mint
-  VERSION = '0.2.7'
+  VERSION = '0.2.8'
 end

metadata CHANGED

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mint
 version: !ruby/object:Gem::Version
-  version: 0.2.7
+  version: 0.2.8
   prerelease:
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2011-08-10 00:00:00.000000000Z
+date: 2011-08-11 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tilt
-  requirement: &70148467851220 !ruby/object:Gem::Requirement
+  requirement: &70150881334580 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70148467851220
+  version_requirements: *70150881334580
 - !ruby/object:Gem::Dependency
   name: rdiscount
-  requirement: &70148467850480 !ruby/object:Gem::Requirement
+  requirement: &70150881336760 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70148467850480
+  version_requirements: *70150881336760
 - !ruby/object:Gem::Dependency
   name: erubis
-  requirement: &70148467849680 !ruby/object:Gem::Requirement
+  requirement: &70150881338620 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70148467849680
+  version_requirements: *70150881338620
 - !ruby/object:Gem::Dependency
   name: haml
-  requirement: &70148467848720 !ruby/object:Gem::Requirement
+  requirement: &70150881340960 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,10 +54,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70148467848720
+  version_requirements: *70150881340960
 - !ruby/object:Gem::Dependency
   name: sass
-  requirement: &70148467847980 !ruby/object:Gem::Requirement
+  requirement: &70150881345260 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,10 +65,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70148467847980
+  version_requirements: *70150881345260
 - !ruby/object:Gem::Dependency
   name: rdiscount
-  requirement: &70148467847080 !ruby/object:Gem::Requirement
+  requirement: &70150892156560 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -76,10 +76,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70148467847080
+  version_requirements: *70150892156560
 - !ruby/object:Gem::Dependency
   name: liquid
-  requirement: &70148467846440 !ruby/object:Gem::Requirement
+  requirement: &70150892061900 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -87,10 +87,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70148467846440
+  version_requirements: *70150892061900
 - !ruby/object:Gem::Dependency
   name: less
-  requirement: &70148467845440 !ruby/object:Gem::Requirement
+  requirement: &70150892061440 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -98,10 +98,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70148467845440
+  version_requirements: *70150892061440
 - !ruby/object:Gem::Dependency
   name: radius
-  requirement: &70148467825500 !ruby/object:Gem::Requirement
+  requirement: &70150892060900 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -109,10 +109,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70148467825500
+  version_requirements: *70150892060900
 - !ruby/object:Gem::Dependency
   name: markaby
-  requirement: &70148467824800 !ruby/object:Gem::Requirement
+  requirement: &70150892060360 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -120,10 +120,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70148467824800
+  version_requirements: *70150892060360
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70148467823900 !ruby/object:Gem::Requirement
+  requirement: &70150892059940 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -131,10 +131,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70148467823900
+  version_requirements: *70150892059940
 - !ruby/object:Gem::Dependency
   name: cucumber
-  requirement: &70148467823220 !ruby/object:Gem::Requirement
+  requirement: &70150892059400 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -142,10 +142,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70148467823220
+  version_requirements: *70150892059400
 - !ruby/object:Gem::Dependency
   name: aruba
-  requirement: &70148467822400 !ruby/object:Gem::Requirement
+  requirement: &70150892058860 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -153,7 +153,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70148467822400
+  version_requirements: *70150892058860
 description:
 email: david@allthingsprogress.com
 executables: