middlemac-extras 1.0.6 → 1.0.7

data/documentation_project/source/stylesheets/_middlemac_minimal.scss

@@ -514,3 +514,284 @@ div.image_article:after
 	display: table;
 	clear: both;
 }
+
+//*************************************
+//	For partials extracted from YARD
+//*************************************
+
+$yard_color_symbol: rgba(0,136,204,1);
+$yard_font_mono: Menlo, Consolas, Monaco, Courier, monospace;
+
+div.attr_details,
+div.method_details_list
+{
+	.inline
+	{
+		display: inline;
+
+		p:first-child
+		{
+			display: inline;
+		}
+	}
+
+	.method_details
+	{
+		border-top: 1px dotted #aaa;
+		margin-top: 15px;
+		padding-top: 0;
+
+		&.first
+		{
+			border: 0;
+		}
+	}
+
+	p.signature,
+	h3.signature
+	{
+		font-size: 0.9em;
+		font-weight: normal;
+		font-family: $yard_font_mono;
+		padding: 6px 10px;
+		margin-top: 18px;
+		background: #f2f3ff;
+		border: 1px solid #d8d8e5;
+		-moz-border-radius: 3px;
+		-webkit-border-radius: 3px;
+		color: $yard_color_symbol;
+
+		strong
+		{
+			color: inherit;;
+		}
+
+		tt
+		{
+			font-family: inherit;
+		}
+
+		.overload
+		{
+			display: block;
+		}
+
+		.extras
+		{
+			font-weight: normal;
+			font-family: sans-serif;
+			color: #444;
+			font-size: 1em;
+		}
+
+		.not_defined_here,
+		.aliases
+		{
+			display: block;
+			font-weight: normal;
+			font-size: 0.9em;
+			font-family: $yard_font_mono;
+			margin-top: 0px;
+			color: #555;
+
+			.names
+			{
+				font-family: $yard_font_mono;
+				font-weight: bold;
+				color: #000;
+				font-size: 1.2em;
+			}
+		}
+	}
+
+	div.docstring
+	{
+		div.discussion
+		{
+
+		}
+	}
+
+	div.tags
+	{
+		margin-bottom: 12px;
+
+		.tag_title
+		{
+			font-size: 1em;
+			margin-bottom: 0;
+			font-weight: bold; }
+
+		ul
+		{
+			margin-top: 5px;
+			padding-left: 30px;
+			list-style: square;
+
+			li {
+				margin-bottom: 3px;
+			}
+
+			.name
+			{
+				font-family: $yard_font_mono;
+				font-weight: bold;
+			}
+
+			.note
+			{
+				padding: 3px 6px;
+			}
+
+		}
+
+		.examples
+		{
+			.tag_title
+			{
+				margin-bottom: 10px;
+				font-weight: bold;
+			}
+
+			.inline p
+			{
+				padding: 0;
+				margin: 0;
+				margin-left: 15px;
+				font-weight: bold;
+				font-size: 0.9em;
+			}
+		}
+
+		.overload
+		{
+			.overload_item
+			{
+				list-style: none;
+				margin-bottom: 25px;
+
+				.signature
+				{
+					padding: 2px 8px;
+					background: #e5e8ff;
+					border: 1px solid #d8d8e5;
+					-moz-border-radius: 3px;
+					-webkit-border-radius: 3px;
+				}
+			}
+
+			.signature
+			{ margin-left: -15px;
+				font-family: monospace;
+				display: block;
+				font-size: 1.1em;
+			}
+
+			.docstring
+			{
+				margin-top: 15px;
+			}
+
+		}
+
+		/* syntax highlighting */
+		//.source_code { display: none; padding: 3px 8px; border-left: 8px solid #ddd; margin-top: 5px; }
+		//#filecontents pre.code, .docstring pre.code, .source_code pre { font-family: monospace; }
+		//#filecontents pre.code, .docstring pre.code { display: block; }
+		//.source_code .lines { padding-right: 12px; color: #555; text-align: right; }
+
+		#filecontents pre.code,
+		.docstring pre.code,
+		pre.example
+		{
+			padding: 5px 12px; margin-top: 4px; border: 1px solid #eef; background: #f5f5ff;
+		}
+
+		pre.code
+		{
+			color: #000;
+
+			info.file { color: #555; }
+
+			.val { color: #036A07; }
+
+			.tstring_content,
+			.heredoc_beg,
+			.heredoc_end,
+			.qwords_beg,
+			.qwords_end,
+			.tstring,
+			.dstring
+			{
+				color: #036A07;
+			}
+
+			.fid,
+			.rubyid_new,
+			.rubyid_to_s,
+			.rubyid_to_sym,
+			.rubyid_to_f,
+			.dot + pre.code .id,
+			.rubyid_to_i pre.code .rubyid_each
+			{
+				color: #0085FF;
+			}
+
+			.comment
+			{
+				color: #0066FF;
+			}
+
+			.const,
+			.constant
+			{
+				color: #585CF6;
+			}
+
+			.label,
+			.symbol
+			{
+				color: #C5060B;
+			}
+
+			.kw,
+			.rubyid_require,
+			.rubyid_extend,
+			.rubyid_include
+			{
+				color: #0000FF;
+			}
+
+			.ivar
+			{
+				color: #318495;
+			}
+
+			.gvar,
+			.rubyid_backref,
+			.rubyid_nth_ref
+			{
+				color: #6D79DE;
+			}
+
+			.regexp,
+			.dregexp
+			{
+				color: #036A07;
+			}
+
+			a
+			{
+				border-bottom: 1px dotted #bbf;
+			}
+
+		}
+	}
+
+	table.source_code
+	{
+		display: none;
+	}
+
+
+}

data/features/helpers.feature

@@ -0,0 +1,39 @@
+Feature: Provide helpers and resource items to make multiple targets easy to manage.
+
+  As a software developer
+  I want to use helpers and resource items
+  In order to enable automatic navigation of items.
+  
+  Background:
+    Given a built app at "middlemac_extras_app"
+    
+  Scenario:
+    The css_image_sizes helper should return CSS for every image in the project
+    and @2x images should have proper widths and heights, too.
+    When I cd to "build"
+    And the file "index.html" should contain "img[src$='/images/middlemac-extras-small.png'] { max-width: 128px; max-height: 128px; }"
+    And the file "index.html" should contain "img[src$='/images/middlemac-extras-small@2x.png'] { max-width: 128px; max-height: 128px; }"
+    And the file "index.html" should contain "img[src$='/images/middlemac-extras-smaller.png'] { max-width: 64px; max-height: 64px; }"
+    
+
+  Scenario:
+    The md_images helper should return Markdown references for every image in
+    the project.
+    When I cd to "build"
+    And the file "index.html" should contain '[middlemac-extras-small]: /images/middlemac-extras-small.png'
+    And the file "index.html" should contain '[middlemac-extras-small@2x]: /images/middlemac-extras-small@2x.png'
+    And the file "index.html" should contain '[middlemac-extras-smaller]: /images/middlemac-extras-smaller.png'
+    
+
+  Scenario:
+    The md_links helper should return Markdown references for every HTML file
+    in the project, and should include a title generated from the front matter.
+    When I cd to "build"
+    And the file "index.html" should contain '[index]: / "Fixture for middlemac-extras"'
+    
+  Scenario:
+    The extended image tag should include srcset automatically if @2x images are
+    present, and not include a srcset if not.
+    When I cd to "build"
+    And the file "index.html" should contain 'img src="/images/middlemac-extras-small.png" srcset="/images/middlemac-extras-small@2x.png 2x" alt="Middlemac extras small"'
+    And the file "index.html" should contain 'img src="/images/middlemac-extras-smaller.png" alt="Middlemac extras smaller"'

data/features/support/env.rb

@@ -0,0 +1,20 @@
+PROJECT_ROOT_PATH = File.dirname(File.dirname(File.dirname(__FILE__)))
+ENV['TEST'] = 'true'
+
+require 'middleman'
+require 'middleman-core/step_definitions'
+require File.join(PROJECT_ROOT_PATH, 'lib', 'middlemac-extras')
+
+
+require 'cucumber/formatter/pretty'
+class QuietFormatter < Cucumber::Formatter::Pretty
+  def initialize(runtime, io, options)
+     $stderr = File.new( '/dev/null', 'w' )
+    super(runtime, io, options)
+  end
+  
+  def after_features(features)
+    $stderr = STDOUT
+    super(features)
+  end
+end

data/fixtures/middlemac_extras_app/config.rb

@@ -0,0 +1,7 @@
+activate :MiddlemacExtras do |config|
+  config.retina_srcset = true
+  config.img_auto_extensions = true
+  config.img_auto_extensions_order = %w(.svg .png .jpg .jpeg .gif .tiff .tif)
+end
+
+set :relative_links, true

data/fixtures/middlemac_extras_app/source/index.html.md.erb

@@ -0,0 +1,31 @@
+---
+title: Fixture for middlemac-extras
+---
+# css_image_sizes
+
+~~~
+<%= css_image_sizes %>
+~~~
+
+# md_images
+
+~~~
+<%= md_images %>
+~~~
+
+# md_links
+
+~~~
+<%= md_links %>
+~~~
+
+# extended image_tag
+
+~~~
+<%= image_tag 'middlemac-extras-small' %>
+~~~
+
+~~~
+<%= image_tag 'middlemac-extras-smaller' %>
+~~~
+

data/lib/middlemac-extras/extension.rb

@@ -1,11 +1,12 @@
-################################################################################
-# extension.rb
-#  This file constitutes the framework for the bulk of this extension.
-################################################################################
 require 'middleman-core'
 require 'pathname'
 require 'fastimage'
 
+################################################################################
+# This extension provides Middleman several useful helpers and extends some of
+# its built-in helpers to offer more features.
+# @author Jim Derry <balthisar@gmail.com>
+################################################################################
 class MiddlemacExtras < ::Middleman::Extension
 
   ############################################################
@@ -17,8 +18,39 @@ class MiddlemacExtras < ::Middleman::Extension
   option :img_auto_extensions_order, %w(.svg .png .jpg .jpeg .gif .tiff .tif), 'Specifies the order to support automatic image extensions.'
 
 
+  # @!group Extension Configuration
+
+  # @!attribute [rw] options[:retina_srcset]=
+  # This option determines whether or not the enhanced `image_tag` helper will
+  # be used to include an @2x `srcset` attribute automatically. This automatic
+  # behavior will only be applied if the image asset exists on disk and this
+  # option is set to `true`.
+  # @param [Boolean] value `true` or `false` to enable or disable this feature.
+  # @return [Boolean] Returns the current value of this option.
+
+  # @!attribute [rw] options[:img_auto_extensions]=
+  # This option determines whether or not to support specifying images without
+  # using a file name extension. If set to `true` then the `image_tag` helper
+  # will work for images even if you don’t specify an extension, but only if a
+  # file exists on disk that has one of the extensions in 
+  # `:img_auto_extensions_order`.
+  # @param [Boolean] value `true` or `false` to enable or disable this feature.
+  # @return [Boolean] Returns the current value of this option.
+
+  # @!attribute [rw] options[:img_auto_extensions_order]=
+  # This option defines the eligible file name extensions and their precedence
+  # when you specify an image without an extension using the `image_tag` helper.
+  # Set this to an array of image file extensions in your desired order of
+  # of precedence.
+  # @param [Array<String>] value Set to an array of image extensions.
+  # @return [Array<String>] Returns the current value of this option.
+
+  # @!endgroup
+
+
   ############################################################
   # initialize
+  # @visibility private
   ############################################################
   def initialize(app, options_hash={}, &block)
 
@@ -33,7 +65,8 @@ class MiddlemacExtras < ::Middleman::Extension
 
   ############################################################
   # after_configuration
-  #  Callback occurs before `before_build`.
+  #   Callback occurs before `before_build`.
+  # @visibility private
   #############################################################
   def after_configuration
 
@@ -56,8 +89,13 @@ class MiddlemacExtras < ::Middleman::Extension
   helpers do
 
     #--------------------------------------------------------
-    # md_links
-    #   Adds simple markdown links where needed.
+    # This helper provides access to `middlemac-extras`’ 
+    # index of links in Markdown reference format, enabling
+    # you to use reference-style links in documents. Because
+    # this helper includes literal Markdown, it’s only useful
+    # in Markdown documents.
+    # @return [String] Returns a string with the Markdown
+    #   index of every page in your project.
     #--------------------------------------------------------
     def md_links
       extensions[:MiddlemacExtras].md_links_b
@@ -65,8 +103,13 @@ class MiddlemacExtras < ::Middleman::Extension
 
 
     #--------------------------------------------------------
-    # md_images
-    #   Adds simple markdown image links where needed.
+    # This helper provides access to `middlemac-extras`’ 
+    # index of images in Markdown reference format, enabling
+    # you to use reference-style images in documents. Because
+    # this helper includes literal Markdown, it’s only useful
+    # in Markdown documents.
+    # @return [String] Returns a string with the Markdown
+    #   index of every image in your project.
     #--------------------------------------------------------
     def md_images
       extensions[:MiddlemacExtras].md_images_b
@@ -74,8 +117,14 @@ class MiddlemacExtras < ::Middleman::Extension
 
 
     #--------------------------------------------------------
-    # css_image_sizes
-    #   Generates image size CSS information for all images.
+    # This helper provides CSS for every image in your
+    # project. Each image will have a declaration that sets
+    # `max-width` and `max-height` to the actual size of the
+    # image. Proper @2x image support is included. It’s most
+    # useful to use this helper in a `some_file.css.erb`
+    # file.
+    # @return [String] Returns a string with the CSS markup
+    #   for every image found in your project.
     #--------------------------------------------------------
     def css_image_sizes
       extensions[:MiddlemacExtras].md_sizes_b
@@ -83,10 +132,25 @@ class MiddlemacExtras < ::Middleman::Extension
 
 
     #--------------------------------------------------------
-    # image_tag(path, params={})
-    #   Add automatic srcset if an @2x image is present and
-    #   no srcset is already specified. Also support the
-    #   use of extension-less images.
+    # With the proper options enabled this helper extends
+    # the built-in functionality of **Middleman**’s helpers
+    # in a couple of ways. With `:retina_srcset` enabled,
+    # automatic `srcset` attributes will be applied to
+    # `<img>` tags if an @2x version of the specified image
+    # is found. With `:img_auto_extensions` it’s possible to
+    # specify image names without the file name extension.
+    # @param [String] path Specify path to the image file.
+    # @param [Hash] params Optional parameters to pass to
+    #   the helper. **Middleman** (and other extensions)
+    #   provide other parameters in addition to these.
+    # @option params [Boolean] :img_auto_extensions Allows
+    #   control of the automatic image extensions option
+    #   on a per-use basis.
+    # @option params [Boolean] :retina_srcset Allows control
+    #   of the automatic @2x images feature on a per-use
+    #   basis. 
+    # @return [String] Returns an HTML `<img>` tag.
+    # @group Extended Helpers
     #--------------------------------------------------------
     def image_tag(path, params={})
       params.symbolize_keys!
@@ -176,13 +240,18 @@ class MiddlemacExtras < ::Middleman::Extension
 
 
   ############################################################
-  #  Instance Methods
+  # Instance Methods
+  # @!group Instance Methods
   ############################################################
 
-  #--------------------------------------------------------
-  # md_links_b
-  #   Adds simple markdown links where needed.
-  #--------------------------------------------------------
+
+  #########################################################
+  # This accessor for @md_links_b lazily populates the
+  # backing variable and buffers it for repeated use. In
+  # the event of file changes, a server restart is needed.
+  # @returns [String] Returns the Markdown reference list.
+  # @!visibility private
+  #########################################################
   def md_links_b
     unless @md_links_b
       @md_links_b = get_link_data('text/html', 'application/xhtml')
@@ -194,9 +263,13 @@ class MiddlemacExtras < ::Middleman::Extension
   end
 
 
-  #--------------------------------------------------------
-  # md_images_b
-  #--------------------------------------------------------
+  #########################################################
+  # This accessor for @md_images_b lazily populates the
+  # backing variable and buffers it for repeated use. In
+  # the event of file changes, a server restart is needed.
+  # @returns [String] Returns the Markdown reference list.
+  # @!visibility private
+  #########################################################
   def md_images_b
     unless @md_images_b
       @md_images_b = get_link_data('image/')
@@ -207,13 +280,15 @@ class MiddlemacExtras < ::Middleman::Extension
   end
 
 
-  #--------------------------------------------------------
-  # get_link_data( *types )
-  #   Get all of the required link data for generating
-  #   markdown shortcuts.
-  # @param  types should be the content_type to check.
-  # @return an array of hashes with file data.
-  #--------------------------------------------------------
+  #########################################################
+  # Get all of the required link data for generating
+  # markdown shortcuts for the two property accessors.
+  # @param [va_list<String>] types One or more MIME types
+  #   specifying the file types for which to build links.
+  # @return [Array<Hash>] An array of hashes containing
+  #   the file data.
+  # @!visibility private
+  #########################################################
   def get_link_data( *types )
     all_links = []
     # We'll include a sort by number of path components in this chain so
@@ -244,10 +319,14 @@ class MiddlemacExtras < ::Middleman::Extension
   end
 
 
-  #--------------------------------------------------------
-  # md_sizes_b
-  #  For every image resource, try to build the size.
-  #--------------------------------------------------------
+  #########################################################
+  # For every image resource in the project, attempt to
+  # build the CSS rules. Only bitmap images are supported,
+  # as vectors (e.g., SVG) don’t have a specific size.
+  # @returns [String] Returns the CSS stylesheet with the
+  #   maximum width and height for each image.
+  # @!visibility private
+  #########################################################
   def md_sizes_b
     unless @md_sizes_b
       @md_sizes_b = []
@@ -282,11 +361,19 @@ class MiddlemacExtras < ::Middleman::Extension
   end
   
   
-  #--------------------------------------------------------
-  # with_extension_proposal( path, ext )
-  #  Returns a file with an extension if found; otherwise
-  #  it returns the original file.
-  #--------------------------------------------------------
+  #########################################################
+  # Returns a file with an extension if found; otherwise
+  # it returns the original file. This is used to search
+  # for images for which no file name extension has been
+  # provided.
+  # @param [String] path Specifies the image without an
+  #   extension, which is to be checked.
+  # @param [String] ext Specifies the extension to check.
+  # @returns [String] Returns the path of the image with
+  #   an extension (if found), or returns the original
+  #   `path` parameter.
+  # @!visibility private
+  #########################################################
   def with_extension_proposal( path, ext )
     return path unless File.extname(path) == '' && app.extensions[:MiddlemacExtras].options[:img_auto_extensions]
   
@@ -311,10 +398,15 @@ class MiddlemacExtras < ::Middleman::Extension
   end
 
 
-  #--------------------------------------------------------
-  # say
-  #  Output colored messages using ANSI codes.
-  #--------------------------------------------------------
+  #########################################################
+  # Output colored messages using ANSI codes.
+  # @param [String] message The message to output to the
+  #   console.
+  # @param [Symbol] color The color in which to display
+  #   the message.
+  # @returns [Void]
+  # @!visibility private
+  #########################################################
   def say(message = '', color = :reset)
     colors = { :blue   => "\033[34m",
                :cyan   => "\033[36m",

data/lib/middlemac-extras/version.rb

@@ -1,5 +1,5 @@
 module Middleman
     module MiddlemacExtras
-        VERSION = '1.0.6'
+        VERSION = '1.0.7'
     end
 end

data/middlemac-extras.gemspec

@@ -2,6 +2,8 @@
 $:.push File.expand_path('../lib', __FILE__)
 require 'middlemac-extras/version'
 
+mm_needed = ['~> 4.1', '>= 4.1.7']
+
 Gem::Specification.new do |s|
   s.name        = 'middlemac-extras'
   s.version     = Middleman::MiddlemacExtras::VERSION
@@ -19,9 +21,15 @@ 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('fastimage', ['~> 1.9', '>= 1.9.0'])
+  s.add_runtime_dependency('middleman-cli', mm_needed)
+  s.add_runtime_dependency('fastimage', ['~> 2.0'])
+  
+  # Development dependencies
+  s.add_development_dependency 'middleman', mm_needed
+  s.add_development_dependency 'bundler',   '>= 1.6'
+  s.add_development_dependency 'rake',      '>= 10.3'
+  s.add_development_dependency 'git'
 end