middleman-targets 1.0.3 → 1.0.4

data/lib/middleman-targets/extension.rb

@@ -1,23 +1,114 @@
-################################################################################
-# extension.rb
-#  This file constitutes the framework for the bulk of this extension.
-################################################################################
 require 'middleman-core'
 
+################################################################################
+# This extension provides Middleman the ability to build and serve multiple
+# targets, and includes resource extensions and helpers to take advantage of
+# this new feature.
+# @author Jim Derry <balthisar@gmail.com>
+################################################################################
 class MiddlemanTargets < ::Middleman::Extension
 
   ############################################################
   # Define the options that are to be set within `config.rb`
   # as Middleman *application* (not extension) options.
   ############################################################
+
   define_setting :target, 'default', 'The default target to process if not specified.'
   define_setting :targets, { :default => { :features => {} } } , 'A hash that defines many characteristics of the target.'
   define_setting :target_magic_images, true, 'Enable magic images for targets.'
-  define_setting :target_magic_word, 'all', 'The magic image prefix for asset substitution.'
+  define_setting :target_magic_word, 'all', 'The magic image prefix for image substitution.'
+
+  # @!group Middleman Configuration
+
+  # @!attribute [rw] config[:target]=
+  # Indicates the current target that is being built or served. When
+  # set in `config.rb` it indicates the default target if one is not
+  # specified on the command line.
+  # @param [Symbol] value The target from `config[:targets]` that should
+  #   be used as the default.
+  # @return [Symbol] Returns the current target.
+  # @note This is a Middleman application level config option.
+
+
+  # @!attribute [rw] config[:targets]=
+  # A hash that defines all of the characteristics of your individual targets.
+  # The `build_dir` and `features` keys in a target have special meanings;
+  # other keys can be added arbitrarily and helpers can fetch these for you.
+  # A best practice is to assign the same features to _all_ of your targets and
+  # toggle them `on` or `off` on a target-specific basis.
+  # @example You might define this in your `config.rb` like this:
+  #     config[:targets] = {
+  #       :free =>
+  #           {
+  #               :sample_key => 'People who use free versions don\'t drive profits.',
+  #               :build_dir  => 'build (%s)',
+  #               :features   =>
+  #                   {
+  #                       :feature_advertise_pro => true,
+  #                       :insults_user          => true,
+  #                       :grants_wishes         => false,
+  #                   }
+  #           },
+  #
+  #           :pro =>
+  #           {
+  #               :sample_key => 'You are a valued contributor to our balance sheet!',
+  #               :features =>
+  #                   {
+  #                       :feature_advertise_pro => false,
+  #                       :insults_user          => false,
+  #                       :grants_wishes         => true,
+  #                   }
+  #           },
+  #       }
+  # @param [Hash] value The complete definition of your targets, their
+  #   features, and other keys-value pairs that you wish to include.
+  # @return [Hash] Returns the attributes of your targets.
+  # @note This is a Middleman application level config option.
+
+
+  # @!attribute [rw] config[:target_magic_images]=
+  # This option is used to enable or disable the target magic images feature.
+  # If it's `true` then the `image_tag` helper will attempt to substitute
+  # target-specific images instead of the specified image, if the specified
+  # image begins with `:target_magic_word`.
+  # @param [Boolean] value Specify whether or not automatic target-specific
+  #   image substitution should be enabled.
+  # @return [Boolean] Returns the current state of this option.
+  # @note This is a Middleman application level config option.
+
+
+  # @!attribute [rw] config[:target_magic_word]=
+  # Indicates the magic image prefix for image substitution with the
+  # `image_tag` helper when `:target_magic_images` is enabled. For example
+  # if you specify `all-image.png` and `pro-image.png` exists, then the
+  # latter will be used by the helper instead of the former.
+  # @param [String] value Indicate the prefix that should indicate and image
+  #   the should be substituted, such as `all`.
+  # @return [String] Returns the current magic prefix.
+  # @note This is a Middleman application level config option.
+
+
+  # @!attribute [rw] config[:build_dir]=
+  # Indicates where **Middleman** will put build output. This standard config
+  # value will be treated as a *prefix*; for example if the current target is
+  # `:pro` and this value is set to its default `build`, then the actual build
+  # directory will be `build (pro)/`.
+  #
+  # If the `build_dir` key is present for any of the `config[:targets]`, they
+  # will override this setting.
+  # @param [String] value Indicate the build directory prefix that should be
+  #   used for build output.
+  # @return [String] Returns the current value of this configuration setting.
+  # @note This is a Middleman application level config option.
+
+
+  # @!endgroup
 
 
   ############################################################
   # initialize
+  # @!visibility private
   ############################################################
   def initialize(app, options_hash={}, &block)
 
@@ -30,6 +121,7 @@ class MiddlemanTargets < ::Middleman::Extension
   ############################################################
   # after_configuration
   #  Handle the --target cli setting.
+  # @!visibility private
   #############################################################
   def after_configuration
 
@@ -83,12 +175,10 @@ class MiddlemanTargets < ::Middleman::Extension
     resources.each do |resource|
 
       #--------------------------------------------------------
-      #  valid_features
-      #    Returns an array of valid features for this page
-      #    based on the current target, i.e., features that
-      #    are true for the current target. These are the
-      #    only features that can be used with frontmatter
-      #    :target or :exclude.
+      # Returns an array of valid features for a resource
+      # based on the current target, i.e., features that
+      # are true for the current target.
+      # @return [Array] Returns an array of features.
       #--------------------------------------------------------
       def resource.valid_features
         @app.config[:targets][@app.config[:target]][:features].select { |k, v| v }.keys
@@ -96,21 +186,22 @@ class MiddlemanTargets < ::Middleman::Extension
 
 
       #--------------------------------------------------------
-      #  targeted?
-      #    Determines if the resource is eligible for
-      #    inclusion in the current page based on the front
-      #    matter `target` and `exclude` data fields:
-      #      - if frontmatter:target is used, the target or
-      #        feature appears in the frontmatter, and
-      #      - if frontmatter:exclude is used, the target or
-      #        enabled feature does NOT appear in the
-      #        frontmatter.
+      # Determines if the resource is eligible for inclusion
+      # in the current target based on the front matter data
+      # `target` and `exclude` fields.
+      #
+      #   * If **frontmatter:target** is used, the target or
+      #     feature appears in the frontmatter, and
+      #   * If **frontmatter:exclude** is used, the target or
+      #     enabled feature does NOT appear in the
+      #     frontmatter
       #
-      #    In general you won't use this resource method
-      #    because resources will already be excluded before
-      #    you have a chance to check them, and so any
-      #    leftover resources will always return true for
-      #    this method.
+      # In general you won't use this resource method because
+      # resources will already be excluded before you have a
+      # chance to check them, and so any leftover resources
+      # will always return `true` for this method.
+      # @return [Boolean] Returns a value indicating whether
+      #   or not this resource belongs in the current target.
       #--------------------------------------------------------
       def resource.targeted?
         target_name = @app.config[:target]
@@ -153,16 +244,16 @@ class MiddlemanTargets < ::Middleman::Extension
 
 
   ############################################################
-  #  Helpers
-  #    Methods defined in this helpers block are available in
-  #    templates.
+  # Helpers
+  #   Methods defined in this helpers block are available in
+  #   templates.
   ############################################################
 
   helpers do
 
     #--------------------------------------------------------
-    # target_name
-    #   Return the current build target.
+    # Return the current build target.
+    # @return [Symbol] Returns the current build target.
     #--------------------------------------------------------
     def target_name
       @app.config[:target]
@@ -170,8 +261,11 @@ class MiddlemanTargets < ::Middleman::Extension
 
 
     #--------------------------------------------------------
-    # target_name?
-    #   Is the current target `proposal`?
+    # Is the current target `proposal`?
+    # @param [String, Symbol] proposal Specifies a proposed
+    #   target.
+    # @return [Boolean] Returns `true` if the current target
+    #   matches the parameter `proposal`.
     #--------------------------------------------------------
     def target_name?( proposal )
       @app.config[:target] == proposal.to_sym
@@ -179,8 +273,12 @@ class MiddlemanTargets < ::Middleman::Extension
 
 
     #--------------------------------------------------------
-    # target_feature?
-    #   Does the target have the feature `feature`?
+    # Does the target have the feature `feature` enabled?
+    # @param [String, Symbol] feature Specifies a proposed
+    #   feature.
+    # @return [Boolean] Returns `true` if the current target
+    #   has the features `feature` and the features is
+    #   enabled.
     #--------------------------------------------------------
     def target_feature?( feature )
       features = @app.config[:targets][@app.config[:target]][:features]
@@ -189,9 +287,13 @@ class MiddlemanTargets < ::Middleman::Extension
 
 
     #--------------------------------------------------------
-    # target_value( key )
-    #   Attempts to return arbitrary key values for the
-    #   current target.
+    # Attempts to return arbitrary key values for the key
+    #   `key` for the current target.
+    # @param [String, Symbol] key Specifies the desired key
+    #   to look up.
+    # @return [String, Nil] Returns the value for `key` in
+    #   the `:targets` structure, or `nil` if it doesn’t
+    #   exist.
     #--------------------------------------------------------
     def target_value( key )
       target_values = @app.config[:targets][@app.config[:target]]
@@ -200,12 +302,30 @@ class MiddlemanTargets < ::Middleman::Extension
 
 
     #--------------------------------------------------------
-    # image_tag
-    #   Override the built-in version in order to support:
-    #    - automatic target-specific images. Note that this
-    #      only works on local files.
-    #    - target and feature dependent images.
-    #    - absolute paths
+    # Override the built-in `image-tag` helper in order to
+    # support additional features.
+    #
+    #   * Automatic target-specific images. Note that this
+    #     only works on local files, and only if enabled
+    #     with the option `:target_magic_images`.
+    #   * Target and feature dependent images using the
+    #     `params` hash.
+    #   * Absolute paths, which Middleman sometimes bungles.
+    #
+    # Note that in addition to the options described below,
+    # `middleman-targets` inherits all of the built-in
+    # option parameters as well.
+    #
+    # @param [String] path The path to the image file.
+    # @param [Hash] params Optional parameters to pass to
+    #   the helper.
+    # @option params [String, Symbol] :target This image
+    #   tag will only be applied if the current target is
+    #   `target`.
+    # @option params [String, Symbol] :feature This image
+    #   tag will only be applied if the current target
+    #   enables the feature `feature`.
+    # @return [Void]
     #--------------------------------------------------------
     def image_tag(path, params={})
       params.symbolize_keys!
@@ -237,7 +357,6 @@ class MiddlemanTargets < ::Middleman::Extension
       super(path, params)
     end
 
-
   end #helpers
 
 
@@ -246,12 +365,21 @@ class MiddlemanTargets < ::Middleman::Extension
   ############################################################
 
 
-  #--------------------------------------------------------
-  # target_specific_proposal( file )
-  #  Returns a target-specific proposed file when given
-  #  a user-specified file, and will return the same file
-  #  if not enabled or doesn't begin with the magic word.
-  #--------------------------------------------------------
+  #########################################################
+  # Returns a target-specific proposed file when given
+  #   a user-specified file, and will return the same file
+  #   if not enabled or doesn't begin with the magic word.
+  #
+  # This method allow other implementations of `image-tag`
+  #   to honor this implementation’s use of automatic
+  #   image substitutions.
+  # @param [String] path Specify the path to the image
+  #   for which you want to provide a substitution. This
+  #   image doesn’t have to exist in fact if suitable
+  #   images exist for the current target.
+  # @return [String] Returns the substitute image if one
+  #   was found, otherwise it returns the original path.
+  #########################################################
   def target_specific_proposal( path )
     return path unless @app.config[:target_magic_images] && File.basename(path).start_with?( @app.config[:target_magic_word])
 
@@ -278,10 +406,10 @@ class MiddlemanTargets < ::Middleman::Extension
   end
  
  
-  #--------------------------------------------------------
-  # say
-  #  Output colored messages using ANSI codes.
-  #--------------------------------------------------------
+  #########################################################
+  # Output colored messages using ANSI codes.
+  # @!visibility private
+  #########################################################
   def say(message = '', color = :reset)
     colors = { :blue   => "\033[34m",
                :cyan   => "\033[36m",

data/lib/middleman-targets/middleman-cli/build_all.rb

@@ -1,10 +1,8 @@
-################################################################################
-# build_all.rb
-#  Provides the class necessary for the build_all (all) command.
-################################################################################
-
 require 'middleman-cli'
 
+################################################################################
+# Envelops the class necessary to provide the `build_all`/`all` commands.
+################################################################################
 module Middleman::Cli
 
   ###################################################################
@@ -16,7 +14,8 @@ module Middleman::Cli
     check_unknown_options!
 
     ############################################################
-    # build_all
+    # Build all targets.
+    # @return [Void]
     ############################################################
     def build_all
 

data/lib/middleman-targets/version.rb

@@ -1,5 +1,5 @@
 module Middleman
     module MiddlemanTargets
-        VERSION = '1.0.3'
+        VERSION = '1.0.4'
     end
 end

data/middleman-targets.gemspec

@@ -2,6 +2,8 @@
 $:.push File.expand_path('../lib', __FILE__)
 require 'middleman-targets/version'
 
+mm_needed = ['~> 4.1', '>= 4.1.6']
+
 Gem::Specification.new do |s|
   s.name        = 'middleman-targets'
   s.version     = Middleman::MiddlemanTargets::VERSION
@@ -19,8 +21,13 @@ Gem::Specification.new do |s|
   s.require_paths = ['lib']
   
   # The version of middleman-core your extension depends on
-  s.add_runtime_dependency('middleman-core', ['~> 4.1', '>= 4.1.6'])
+  s.add_runtime_dependency('middleman-core', mm_needed)
 
   # Additional dependencies
-  s.add_runtime_dependency('middleman-cli', ['~> 4.1', '>= 4.1.6'])
+  s.add_runtime_dependency('middleman-cli', mm_needed)
+  
+  # Development dependencies
+  s.add_development_dependency 'middleman', mm_needed
+  s.add_development_dependency 'bundler',   '>= 1.6'
+  s.add_development_dependency 'rake',      '>= 10.3'
 end

data/yard/readme.md

@@ -0,0 +1,6 @@
+This gem provides the ability to generate multiple targets by outfitting
+*Middleman** with additional command line options. The provided helpers make it
+simple to control content that is specific to each target, based on the target
+name or based on feature sets for each target.
+
+It is standalone and can be used in any **Middleman** project.

data/yard/templates/default/fulldoc/html/css/common.css

@@ -0,0 +1 @@
+/* Override this file with custom rules */

data/yard/templates/default/fulldoc/html/css/full_list.css

@@ -0,0 +1,57 @@
+body {
+  margin: 0;
+  font-family: "Lucida Sans", "Lucida Grande", Verdana, Arial, sans-serif;
+  font-size: 13px;
+  height: 101%;
+  overflow-x: hidden;
+}
+
+h1 { padding: 12px 10px; padding-bottom: 0; margin: 0; font-size: 1.4em; }
+.clear { clear: both; }
+#search { position: absolute; right: 5px; top: 9px; padding-left: 24px; }
+#content.insearch #search, #content.insearch #noresults { background: url(data:image/gif;base64,R0lGODlhEAAQAPYAAP///wAAAPr6+pKSkoiIiO7u7sjIyNjY2J6engAAAI6OjsbGxjIyMlJSUuzs7KamppSUlPLy8oKCghwcHLKysqSkpJqamvT09Pj4+KioqM7OzkRERAwMDGBgYN7e3ujo6Ly8vCoqKjY2NkZGRtTU1MTExDw8PE5OTj4+PkhISNDQ0MrKylpaWrS0tOrq6nBwcKysrLi4uLq6ul5eXlxcXGJiYoaGhuDg4H5+fvz8/KKiohgYGCwsLFZWVgQEBFBQUMzMzDg4OFhYWBoaGvDw8NbW1pycnOLi4ubm5kBAQKqqqiQkJCAgIK6urnJyckpKSjQ0NGpqatLS0sDAwCYmJnx8fEJCQlRUVAoKCggICLCwsOTk5ExMTPb29ra2tmZmZmhoaNzc3KCgoBISEiIiIgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACH/C05FVFNDQVBFMi4wAwEAAAAh/hpDcmVhdGVkIHdpdGggYWpheGxvYWQuaW5mbwAh+QQJCAAAACwAAAAAEAAQAAAHaIAAgoMgIiYlg4kACxIaACEJCSiKggYMCRselwkpghGJBJEcFgsjJyoAGBmfggcNEx0flBiKDhQFlIoCCA+5lAORFb4AJIihCRbDxQAFChAXw9HSqb60iREZ1omqrIPdJCTe0SWI09GBACH5BAkIAAAALAAAAAAQABAAAAdrgACCgwc0NTeDiYozCQkvOTo9GTmDKy8aFy+NOBA7CTswgywJDTIuEjYFIY0JNYMtKTEFiRU8Pjwygy4ws4owPyCKwsMAJSTEgiQlgsbIAMrO0dKDGMTViREZ14kYGRGK38nHguHEJcvTyIEAIfkECQgAAAAsAAAAABAAEAAAB2iAAIKDAggPg4iJAAMJCRUAJRIqiRGCBI0WQEEJJkWDERkYAAUKEBc4Po1GiKKJHkJDNEeKig4URLS0ICImJZAkuQAhjSi/wQyNKcGDCyMnk8u5rYrTgqDVghgZlYjcACTA1sslvtHRgQAh+QQJCAAAACwAAAAAEAAQAAAHZ4AAgoOEhYaCJSWHgxGDJCQARAtOUoQRGRiFD0kJUYWZhUhKT1OLhR8wBaaFBzQ1NwAlkIszCQkvsbOHL7Y4q4IuEjaqq0ZQD5+GEEsJTDCMmIUhtgk1lo6QFUwJVDKLiYJNUd6/hoEAIfkECQgAAAAsAAAAABAAEAAAB2iAAIKDhIWGgiUlh4MRgyQkjIURGRiGGBmNhJWHm4uen4ICCA+IkIsDCQkVACWmhwSpFqAABQoQF6ALTkWFnYMrVlhWvIKTlSAiJiVVPqlGhJkhqShHV1lCW4cMqSkAR1ofiwsjJyqGgQAh+QQJCAAAACwAAAAAEAAQAAAHZ4AAgoOEhYaCJSWHgxGDJCSMhREZGIYYGY2ElYebi56fhyWQniSKAKKfpaCLFlAPhl0gXYNGEwkhGYREUywag1wJwSkHNDU3D0kJYIMZQwk8MjPBLx9eXwuETVEyAC/BOKsuEjYFhoEAIfkECQgAAAAsAAAAABAAEAAAB2eAAIKDhIWGgiUlh4MRgyQkjIURGRiGGBmNhJWHm4ueICImip6CIQkJKJ4kigynKaqKCyMnKqSEK05StgAGQRxPYZaENqccFgIID4KXmQBhXFkzDgOnFYLNgltaSAAEpxa7BQoQF4aBACH5BAkIAAAALAAAAAAQABAAAAdogACCg4SFggJiPUqCJSWGgkZjCUwZACQkgxGEXAmdT4UYGZqCGWQ+IjKGGIUwPzGPhAc0NTewhDOdL7Ykji+dOLuOLhI2BbaFETICx4MlQitdqoUsCQ2vhKGjglNfU0SWmILaj43M5oEAOwAAAAAAAAAAAA==) no-repeat center left; }
+#full_list { padding: 0; list-style: none; margin-left: 0; }
+#full_list ul { padding: 0; }
+#full_list li { padding: 5px; padding-left: 12px; margin: 0; font-size: 1.1em; list-style: none; }
+#noresults { padding: 7px 12px; }
+#content.insearch #noresults { margin-left: 7px; }
+ul.collapsed ul, ul.collapsed li { display: none; }
+ul.collapsed.search_uncollapsed { display: block; }
+ul.collapsed.search_uncollapsed li { display: list-item; }
+li a.toggle { cursor: default; position: relative; left: -5px; top: 4px; text-indent: -999px; width: 10px; height: 9px; margin-left: -10px; display: block; float: left; background: url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAASCAYAAABb0P4QAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAAK8AAACvABQqw0mAAAABx0RVh0U29mdHdhcmUAQWRvYmUgRmlyZXdvcmtzIENTM5jWRgMAAAAVdEVYdENyZWF0aW9uIFRpbWUAMy8xNC8wOeNZPpQAAAE2SURBVDiNrZTBccIwEEXfelIAHUA6CZ24BGaWO+FuzZAK4k6gg5QAdGAq+Bxs2Yqx7BzyL7Llp/VfzZeQhCTc/ezuGzKKnKSzpCxXJM8fwNXda3df5RZETlIt6YUzSQDs93sl8w3wBZxCCE10GM1OcWbWjB2mWgEH4Mfdyxm3PSepBHibgQE2wLe7r4HjEidpnXMYdQPKEMJcsZ4zs2POYQOcaPfwMVOo58zsAdMt18BuoVDPxUJRacELbXv3hUIX2vYmOUvi8C8ydz/ThjXrqKqqLbDIAdsCKBd+Wo7GWa7o9qzOQHVVVXeAbs+yHHCH4aTsaCOQqunmUy1yBUAXkdMIfMlgF5EXLo2OpV/c/Up7jG4hhHcYLgWzAZXUc2b2ixsfvc/RmNNfOXD3Q/oeL9axJE1yT9IOoUu6MGUkAAAAAElFTkSuQmCC) no-repeat bottom left; }
+li.collapsed a.toggle { opacity: 0.5; cursor: default; background-position: top left; }
+li { color: #888; cursor: pointer; }
+li.deprecated { text-decoration: line-through; font-style: italic; }
+li.r1 { background: #f0f0f0; }
+li.r2 { background: #fafafa; }
+li:hover { background: #ddd; }
+li small:before { content: "("; }
+li small:after { content: ")"; }
+li small.search_info { display: none; }
+a:link, a:visited { text-decoration: none; color: #05a; }
+li.clicked { background: #05a; color: #ccc; }
+li.clicked a:link, li.clicked a:visited { color: #eee; }
+li.clicked a.toggle { opacity: 0.5; background-position: bottom right; }
+li.collapsed.clicked a.toggle { background-position: top right; }
+#search input { border: 1px solid #bbb; -moz-border-radius: 3px; -webkit-border-radius: 3px; }
+#nav { margin-left: 10px; font-size: 0.9em; display: none; color: #aaa; }
+#nav a:link, #nav a:visited { color: #358; }
+#nav a:hover { background: transparent; color: #5af; }
+.frames #nav span:after { content: ' | '; }
+.frames #nav span:last-child:after { content: ''; }
+
+.frames #content h1 { margin-top: 0; }
+.frames li { white-space: nowrap; cursor: normal; }
+.frames li small { display: block; font-size: 0.8em; }
+.frames li small:before { content: ""; }
+.frames li small:after { content: ""; }
+.frames li small.search_info { display: none; }
+.frames #search { width: 170px; position: static; margin: 3px; margin-left: 10px; font-size: 0.9em; color: #888; padding-left: 0; padding-right: 24px; }
+.frames #content.insearch #search { background-position: center right; }
+.frames #search input { width: 110px; }
+.frames #nav { display: block; }
+
+#full_list.insearch li { display: none; }
+#full_list.insearch li.found { display: list-item; padding-left: 10px; }
+#full_list.insearch li a.toggle { display: none; }
+#full_list.insearch li small.search_info { display: block; }