middleman-targets 1.0.4 → 1.0.5

data/documentation_project/source/partials/helpers_extended.erb

@@ -0,0 +1,139 @@
+
+
+
+
+
+  <div class="method_details_list">
+    
+    
+      <h2>Extended Helpers</h2>
+      
+        <div class="method_details first">
+  <h3 class="signature first" id="image_tag-instance_method">
+  
+    - (<tt>Void</tt>) <strong>image_tag</strong>(path, params = {}) 
+  
+
+  
+
+  
+</h3><div class="docstring">
+  <div class="discussion">
+    <p>Override the built-in <code>image-tag</code> helper in order to
+support additional features.</p>
+
+<ul>
+  <li>Automatic target-specific images. Note that this
+only works on local files, and only if enabled
+with the option <code>:target_magic_images</code>.</li>
+  <li>Target and feature dependent images using the
+<code>params</code> hash.</li>
+  <li>Absolute paths, which Middleman sometimes bungles.</li>
+</ul>
+
+<p>Note that in addition to the options described below,
+<code>middleman-targets</code> inherits all of the built-in
+option parameters as well.</p>
+
+
+  </div>
+</div>
+<div class="tags">
+  <p class="tag_title">Parameters:</p>
+<ul class="param">
+  
+    <li>
+      
+        <span class='name'>path</span>
+      
+      
+        <span class='type'>(<tt>String</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'><p>The path to the image file.</p>
+</div>
+      
+    </li>
+  
+    <li>
+      
+        <span class='name'>params</span>
+      
+      
+        <span class='type'>(<tt>Hash</tt>)</span>
+      
+      
+        <em class="default">(defaults to: <tt>{}</tt>)</em>
+      
+      
+        &mdash;
+        <div class='inline'><p>Optional parameters to pass to
+the helper.</p>
+</div>
+      
+    </li>
+  
+</ul>
+
+  
+    
+    
+    
+    
+    <p class="tag_title">Options Hash (<tt>params</tt>):</p>
+    <ul class="option">
+      
+        <li>
+          <span class="name">:target</span>
+          <span class="type">(<tt>String</tt>, <tt>Symbol</tt>)</span>
+          <span class="default">
+            
+          </span>
+          
+            &mdash; <div class='inline'><p>This image
+tag will only be applied if the current target is
+<code>target</code>.</p>
+</div>
+          
+        </li>
+      
+        <li>
+          <span class="name">:feature</span>
+          <span class="type">(<tt>String</tt>, <tt>Symbol</tt>)</span>
+          <span class="default">
+            
+          </span>
+          
+            &mdash; <div class='inline'><p>This image
+tag will only be applied if the current target
+enables the feature <code>feature</code>.</p>
+</div>
+          
+        </li>
+      
+    </ul>
+  
+
+<p class="tag_title">Returns:</p>
+<ul class="return">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt>Void</tt>)</span>
+      
+      
+      
+    </li>
+  
+</ul>
+
+</div>
+</div>
+      
+    
+  </div>
+
+

data/documentation_project/source/partials/resources.erb

@@ -1,100 +1,110 @@
-<div id="instance_method_details" class="method_details_list">
-  <div class="method_details first ">
-    <h3 class="signature first" id="resource.targeted?-instance_method">
 
-      - (<tt>Boolean</tt>) <strong>resource.targeted?</strong>
 
 
 
 
+  <div class="method_details_list">
+    
+    
+      <h2>Resource Extensions</h2>
+      
+        <div class="method_details first">
+  <h3 class="signature first" id="resource.targeted?-instance_method">
+  
+    - (<tt>Boolean</tt>) <strong>resource.targeted?</strong> 
+  
 
-    </h3><div class="docstring">
-    <div class="discussion">
+  
 
-      <p>Determines if the resource is eligible for inclusion
-        in the current target based on the front matter data
-        <code>target</code> and <code>exclude</code> fields.</p>
+  
+</h3><div class="docstring">
+  <div class="discussion">
+    <p>Determines if the resource is eligible for inclusion
+in the current target based on the front matter data
+<code>target</code> and <code>exclude</code> fields.</p>
 
-      <ul>
-        <li>If <strong>frontmatter:target</strong> is used, the target or
-          feature appears in the frontmatter, and</li>
-        <li>If <strong>frontmatter:exclude</strong> is used, the target or
-          enabled feature does NOT appear in the
-          frontmatter</li>
-      </ul>
+<ul>
+  <li>If <strong>frontmatter:target</strong> is used, the target or
+feature appears in the frontmatter, and</li>
+  <li>If <strong>frontmatter:exclude</strong> is used, the target or
+enabled feature does NOT appear in the
+frontmatter</li>
+</ul>
 
-      <p>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 <code>true</code> for this method.</p>
+<p>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 <code>true</code> for this method.</p>
 
 
-    </div>
   </div>
-    <div class="tags">
-
-      <p class="tag_title">Returns:</p>
-      <ul class="return">
-
-        <li>
-
-
-          <span class='type'>(<tt>Boolean</tt>)</span>
-
+</div>
+<div class="tags">
+  
+<p class="tag_title">Returns:</p>
+<ul class="return">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt>Boolean</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'><p>Returns a value indicating whether
+or not this resource belongs in the current target.</p>
+</div>
+      
+    </li>
+  
+</ul>
 
+</div>
+</div>
+      
+        <div class="method_details ">
+  <h3 class="signature " id="resource.valid_features-instance_method">
+  
+    - (<tt>Array</tt>) <strong>resource.valid_features</strong> 
+  
 
-          &mdash;
-          <div class='inline'><p>Returns a value indicating whether
-            or not this resource belongs in the current target.</p>
-          </div>
+  
 
-        </li>
+  
+</h3><div class="docstring">
+  <div class="discussion">
+    <p>Returns an array of valid features for a resource
+based on the current target, i.e., features that
+are true for the current target.</p>
 
-      </ul>
 
-    </div>
   </div>
+</div>
+<div class="tags">
+  
+<p class="tag_title">Returns:</p>
+<ul class="return">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt>Array</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'><p>Returns an array of features.</p>
+</div>
+      
+    </li>
+  
+</ul>
 
-  <div class="method_details ">
-    <h3 class="signature " id="resource.valid_features-instance_method">
-
-      - (<tt>Array</tt>) <strong>resource.valid_features</strong>
-
-
-
-
-
-    </h3><div class="docstring">
-    <div class="discussion">
-
-      <p>Returns an array of valid features for a resource
-        based on the current target, i.e., features that
-        are true for the current target.</p>
-
-
-    </div>
+</div>
+</div>
+      
+    
   </div>
-    <div class="tags">
-
-      <p class="tag_title">Returns:</p>
-      <ul class="return">
-
-        <li>
-
 
-          <span class='type'>(<tt>Array</tt>)</span>
 
-
-
-          &mdash;
-          <div class='inline'><p>Returns an array of features.</p>
-          </div>
-
-        </li>
-
-      </ul>
-
-    </div>
-  </div>
-
-</div>

data/lib/middleman-targets/extension.rb

@@ -169,6 +169,7 @@ class MiddlemanTargets < ::Middleman::Extension
   ############################################################
   #  Sitemap manipulators.
   #    Add new methods to each resource.
+  # @visibility private
   ############################################################
   def manipulate_resource_list(resources)
 
@@ -326,6 +327,7 @@ class MiddlemanTargets < ::Middleman::Extension
     #   tag will only be applied if the current target
     #   enables the feature `feature`.
     # @return [Void]
+    # @group Extended Helpers
     #--------------------------------------------------------
     def image_tag(path, params={})
       params.symbolize_keys!
@@ -355,13 +357,14 @@ class MiddlemanTargets < ::Middleman::Extension
       end
 
       super(path, params)
-    end
+    end # @endgroup
 
   end #helpers
 
 
   ############################################################
   # Instance Methods
+  # @group Instance Methods
   ############################################################
 
 

data/lib/middleman-targets/version.rb

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

data/yard/readme.md

@@ -1,6 +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.
+**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/template-grouped/default/module/html/method_details_list.erb

@@ -0,0 +1,11 @@
+<% scopes(method_listing(false)) do |list, scope| %>
+  <div id="<%= scope %>_method_details" class="method_details_list">
+    <% groups = list.group_by { |g| g.group.nil? ? 'ZZZ' : g.group }.sort.to_h %>
+    <% groups.each_value do |group| %>
+      <h2><%= group[0].group || "#{scope.to_s.capitalize} Method Details" %></h2>
+      <% group.each_with_index do |meth, i| %>
+        <%= yieldall :object => meth, :owner => object, :index => i %>
+      <% end %>
+    <% end %>
+  </div>
+<% end %>

data/yard/template-partials/default/method_details/setup.rb

@@ -0,0 +1,4 @@
+def init
+  super
+  sections :header, [:method_signature, T('docstring')]
+end

data/yard/template-partials/default/module/html/method_details_list.erb

@@ -0,0 +1,11 @@
+<% scopes(method_listing(false)) do |list, scope| %>
+  <div class="method_details_list">
+    <% groups = list.group_by { |g| g.group.nil? ? 'ZZZ' : g.group }.sort.to_h %>
+    <% groups.each_value do |group| %>
+      <h2><%= group[0].group || "#{scope.to_s.capitalize} Method Details" %></h2>
+      <% group.each_with_index do |meth, i| %>
+        <%= yieldall :object => meth, :owner => object, :index => i %>
+      <% end %>
+    <% end %>
+  </div>
+<% end %>

data/yard/template-partials/default/module/setup.rb

@@ -0,0 +1,6 @@
+include Helpers::ModuleHelper
+
+def init
+  sections :attribute_details, [T('method_details')],
+           :method_details_list, [T('method_details')]
+end

data/yard/template-partials/default/onefile/html/layout.erb

@@ -0,0 +1 @@
+<%= yieldall %>

data/yard/template-partials/default/onefile/html/setup.rb

@@ -0,0 +1,4 @@
+def init
+  super
+  sections :layout, [:all_objects]
+end

data/yard/yard_extensions.rb

@@ -1,73 +1,110 @@
-# Use our own CSS
-YARD::Templates::Engine.register_template_path File.join(File.dirname(__FILE__), 'templates')
+##########################################################################
+# Our template groups the methods by @group instead of lumping all of 
+# them together as instance methods. This is because most of them simply
+# *aren't* instance methods but rather helpers or resource methods.
+# This template will be used by default because .yardopts loads this
+# file; however `rake partials` will override this template via the
+# command line in order to use the `template-partials` instead.
+##########################################################################
+YARD::Templates::Engine.register_template_path File.join(File.dirname(__FILE__), 'template-grouped')
 
+
+##########################################################################
 # Force Yard to parse the helpers block in a Middleman extension.
-# Because they're not truly instance methods, these are forced into their
-# own 'Helpers' group in output.
+#
+#  * Assign a generic "Helpers" group to each item if they don't have
+#    their own @group assignment. Note that @!group doesn't work in this
+#    section.
+#  * Add a @note to each item to distinguish them in a mixed up instance
+#    method detail section.
+##########################################################################
 class HelpersHandler < YARD::Handlers::Ruby::Base
   handles method_call(:helpers)
   namespace_only
 
   def process
-    extra = <<HEREDOC
-@note This is not truly an instance method but a **helper** provided by this class.
-@group Helpers
-HEREDOC
 
     statement.last.last.each do |node|
-      node.docstring.gsub!(/^[\-=]+\n/, '').gsub!(/[\-=]+$/, '') << extra
-      parse_block(node, :owner => self.owner)
-    end
-  end
 
-  def hash_parameters(node)
-    hash = {}
-    return hash unless node
+      extra = ''
 
-    param_strings = node.source.split(/,(?=[^\]]*(?:\[|$))/)
-    param_strings.each do | param |
+      # Find out if there's a @group assigned.
+      extra << '@group Helpers' unless node.docstring.match(/^@group (.*?)$/i)
+
+      # Clean up the doc string because we like - and = borders.
+      # Force the note and group on each of these "fake" methods.
+      if node.docstring
+        docstring = node.docstring
+        docstring = docstring.gsub(/^[\-=]+\n/, '')
+        docstring = docstring.gsub(/[\-=]+$/, '')
+        docstring << extra
+        node.docstring = docstring
+      else
+        node.docstring = extra
+      end
+
+      parse_block(node, :owner => self.owner)
+    end # do
 
-      components = param.split(/\=(?=[^\]]*(?:\[|$))/)
-                       .each { |c| c.strip! }
-      hash[components[0]] = components[1]
-    end
+  end # def
 
-    hash
-  end
-end
+end # class
 
 
+##########################################################################
 # Force Yard to parse the resources.each block in a Middleman extension.
-# Because they're not truly instance methods, these are forced into their
-# own 'Resource Extensions' group in output.
+#
+#  * Assign a generic "Resource Extensions" group to each item if they
+#    don't have their own @group assignment. Note that @!group
+#    doesn't work in this section.
+#  * Force each item to have a `@visibility public` because we will
+#    probably have `@visibility private` in the wrapping method.
+#  * Add a @note to each item to distinguish them in a mixed up instance
+#    method detail section.
+##########################################################################
 class ResourcesHandler < YARD::Handlers::Ruby::Base
   handles :def
   namespace_only
 
   def process
-    note = '@note This is not truly an instance method but a **resource method** added to each resource.'
-    public = '@visibility public'
-    private = '@visibility private'
-
-    if statement.method_name(true).to_sym == :manipulate_resource_list
-
-      statement.docstring = "#{statement.docstring}\n#{private}"
-      # Block consists of everything in the actual `do` block
-      block = statement.last.first.last.last
-      block.each do | node |
-        if node.type == :defs
-          def_docstring = node.docstring.gsub(/^[\-=]+\n/, '').gsub(/[\-=]+$/, '')
-          def_docstring << "#{note}\n#{public}"
-          def_name = node[2][0]
-          object = YARD::CodeObjects::MethodObject.new(namespace, "resource.#{def_name}")
-          register(object)
-          object.dynamic = true
-          object.source = node.source.clone
-          object[:docstring] = def_docstring
-          object[:group] = 'Resource Extensions'
+    extra = <<HEREDOC
+@visibility public
+HEREDOC
+
+    return unless statement.method_name(true).to_sym == :manipulate_resource_list
+
+    # Block consists of everything in the actual `do` block
+    block = statement.last.first.last.last
+    block.each do | node |
+      if node.type == :defs
+        # Clean up the doc string because we like - and = borders.
+        # Force the note and public on each of these "fake" methods.
+        if node.docstring
+          docstring = node.docstring
+          docstring = docstring.gsub(/^[\-=]+\n/, '')
+          docstring = docstring.gsub(/[\-=]+$/, '')
+          docstring << extra
+        else
+          docstring = extra
         end
+
+        # Find out if there's a @group assigned.
+        if ( group = docstring.match(/^@group (.*?)$/i) )
+          group = group[1]
+        else
+          group = 'Resource Extensions'
+        end
+
+        def_name = node[2][0]
+        object = YARD::CodeObjects::MethodObject.new(namespace, "resource.#{def_name}")
+        register(object)
+        object.dynamic = true
+        object.source = node.source.clone
+        object[:docstring] = docstring
+        object[:group] = group
       end
+    end # do
+
+  end # def
 
-    end
-  end
-end
+end # class