Merge pull request #15 from colorful-tones/master

Full on SassDoc integration

Gruntfile.js

@@ -49,6 +49,30 @@ module.exports = function(grunt) {
 				}
 			}
 		},
+
+		sassdoc: {
+			default: {
+				src: [
+					'sass/**/*.scss',
+					'bower_components/bourbon/app/assets/stylesheets',
+					'bower_components/neat/app/assets/stylesheets'
+				],
+				options: {
+					dest: './sassdoc/',
+					display: {
+						access: ['public'],
+						watermark: false
+					},
+					groups: {
+						fontawesomeicons: 'Font Awesome Icons',
+						wds: 'WebDevStudios',
+						'undefined': 'Bourbon & Neat'
+					},
+					description: 'Sass Documentation, which includes Bourbon and Neat documentation as well.',
+					sort: ['group>'],
+				},
+			},
+		},
 
 		autoprefixer: {
 			options: {

package.json

@@ -35,6 +35,7 @@
     "grunt-githooks": "latest",
     "grunt-newer": "latest",
     "grunt-phpcs": "latest",
+    "grunt-sassdoc": "latest",
     "grunt-shell": "latest",
     "grunt-spritesmith": "latest",
     "grunt-update-submodules": "latest",

sass/utilities/mixins/_icon-font-awesome.scss

@@ -1,40 +1,81 @@
-// For adding font icons to elements using CSS pseudo-elements
-// http://jaydenseric.com/blog/fun-with-sass-and-font-icons
-//
-// Example usage:
-//    .my-cool-title {
-//        @include icon(before, '\f04b') {
-//            padding-left: 3px;
-//        }
-//    }
-//
-// 	BE SURE TO ADD YOUR ICON TO _variables.scss, and then you can do this
-//    .menu-toggle {
-//        @include icon(before, favicon) {
-//            padding-left: 3px;
-//        }
-//    }
-//
-//  Be sure to declare your $font-icon font-family in variables.scss
+// ----------------------------------------------------------------------
+
+  // Icons using pseudo-selectors and Font Awesome
+
+// ----------------------------------------------------------------------
+
+////
+/// @author Damon Cook
+/// @group fontawesomeicons
+////
+
+/// For adding Font Awesome font icons to elements using CSS Pseudo Elements
+///
+/// @link http://jaydenseric.com/blog/fun-with-sass-and-font-icons
+/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/Pseudo-elements
+///
+/// @arg {String} $position [before] Set the Pseudo Elements. Accepted arguments: before, after, both
+/// @arg {Boolean | String} $icon [false] - Unicode character, e.g. \f0e0
+/// @arg {Boolean | String} $styles [true] - A place to put margin, padding, etc.
+///
+/// @requires icons
+/// @requires $font-icon
+///
+/// @content [a place for custom styles]
+/// @example scss - Basic Usage Sass
+///    [href^="mailto"] {
+///       @include icon(before, email) {
+///            padding-left: 3px;
+///        }
+///    }
+///
+/// @example scss - Basic Usage CSS Output
+///    [href^="mailto"]:before {
+///        font-family: 'FontAwesome';
+///        font-weight: normal;
+///        font-style: normal;
+///
+///        padding-left: 3px;
+///
+///        content: '\f0e0';
+///
+///        speak: none;
+///    }
+/// 
+/// @example markup - Advanced Usage Sass
+/// // Icons :BEFORE and :AFTER. This should not come up often. Here is a convenient way to handle it: 
+/// // Example HTML: <button class="expand">Expand Horizontally</button>
+///
+///    .expand {
+///        @include icon(both) {
+///            color: gray;
+///        }
+///        @include icon(before, arrow-left, false) {
+///            margin-right: 10px;
+///        }
+///        @include icon(after, arrow-right, false) {
+///            margin-left: 10px;
+///        }
+///    }
 
 @mixin icon($position: before, $icon: false, $styles: true) {
-	@if $position == both {
-		$position: 'before, &:after';
-	}
-	// Either a :before or :after pseudo-element, or both, defaulting to :before
-	&:#{$position} {
-		@if $icon {
-			// A particular icon has been specified
-			content: "#{map-get($icons, $icon)}";
-		}
-		@if $styles {
-			// Supportive icon styles required
-			speak: none;
-			font-style: normal;
-			font-weight: normal;
-			font-family: $font-icon;
-		}
-		// Include any extra rules supplied for the pseudo-element
-		@content;
-	}
-}
+    @if $position == both {
+        $position: 'before, &:after';
+    }
+    // Either a :before or :after pseudo-element, or both, defaulting to :before
+    &:#{$position} {
+        @if $icon {
+            // A particular icon has been specified
+            content: "#{map-get($icons, $icon)}";
+        }
+        @if $styles {
+            // Supportive icon styles required
+            speak: none;
+            font-style: normal;
+            font-weight: normal;
+            font-family: $font-icon;
+        }
+        // Include any extra rules supplied for the pseudo-element
+        @content;
+    }
+}

sass/utilities/mixins/_margin-auto.scss

@@ -0,0 +1,30 @@
+// ----------------------------------------------------------------------
+
+  // Margin auto
+
+// ----------------------------------------------------------------------
+
+////
+/// @author Damon Cook
+/// @group wds
+////
+
+/// Horizontally center a block element
+///
+/// @example scss - Basic Usage Sass
+///    .center-my-block-thingie {
+///        @include margin-auto();
+///    }
+///
+/// @example scss - Basic Usage CSS Output
+///    .center-my-block-thingie {
+///        display: block;
+///        margin-left: auto;
+///        margin-right: auto;
+///    }
+
+@mixin margin-auto {
+	display: block;
+	margin-left: auto;
+	margin-right: auto;
+}

sass/utilities/mixins/_media-queries.scss

@@ -1,5 +1,24 @@
-// Media Queries using Sass List Maps
-// Usage: @include wider-than(desktop);
+////
+/// @author Damon Cook
+/// @group wds
+////
+
+/// Media Queries using Sass List Maps
+/// Define our breakpoints in $breakpoints variable and assign key value pairs in ems.
+///
+/// @example scss - Basic usage
+///    h1 {
+///        margin-left: 20px;
+///
+///        @include wider-than(desktop) {
+///            margin-left: 40px;
+///        }
+///
+/// @output @media (min-width: 85.375em) {}
+///
+/// @param {String} $screen-size - Typical values are phone portrait, phone landscape, desktop, large-desktop. [See available Breakpoints](#variable-breakpoints)
+///
+/// @requires $breakpoints
 
 @mixin wider-than($screen-size) {
 	@if map-has-key($breakpoints, $screen-size) {

sass/utilities/mixins/_word-wrap.scss

@@ -0,0 +1,30 @@
+// ----------------------------------------------------------------------
+
+// Word wrap
+
+// ----------------------------------------------------------------------
+
+// example: @include word-wrap();
+
+/// Wrap non-breaking words
+/// @access public
+/// @author Greg Rickaby
+/// @group wds
+///
+/// @example scss - Basic Usage Sass
+///    .entry-title {
+///        @include word-wrap();
+///    }
+///
+/// @example scss - Basic Usage CSS Output
+///    .entry-title {
+///        	-ms-word-wrap: break-word;
+///			word-wrap: break-word;
+///    }
+
+@mixin word-wrap {
+	-ms-word-wrap: break-word;
+	word-wrap: break-word;
+}
+
+

sass/utilities/mixins/index.scss

@@ -1,3 +1,4 @@
-@import "center-block";
 @import "icon-font-awesome";
-@import "media-queries";
+@import "margin-auto";
+@import "media-queries";
+@import "word-wrap";

sass/utilities/variables/_breakpoints.scss

@@ -1,17 +1,11 @@
-//--------------------------------------------------------------
-// Breakpoints
-// -------------------------------------------------------------
-
-// Define our media query breakpoints in $breakpoints variable
-// and assign key value pairs in ems.
-//
-// see @mixin in _media-queries.scss
-
+// Media Query Breakpoints
+/// Breakpoints Sass list map for Media Queries @mixin
+/// @group wds
 $breakpoints: (
-	large-desktop: 105em,    // 1680px
-	desktop: 85.375em,       // 1366px
-	tablet-landscape: 64em,  // 1024px
-	tablet-portrait: 48em,   // 768px
-	phone-landscape: 40em,   // 640px
-	phone-portrait: 22.5em,  // 360px
+		large-desktop: 105em, // 1680px
+		desktop: 85.375em, // 1366px
+		tablet-landscape: 64em, // 1024px
+		tablet-portrait: 48em, // 768px
+		phone-landscape: 40em, // 640px
+		phone-portrait: 22.5em, // 360px
 );

sass/utilities/variables/_icon-font-awesome.scss

@@ -1,17 +1,24 @@
-//--------------------------------------------------------------
-// Font Awesome Icon Map
-// -------------------------------------------------------------
+/// Declares FontAwesome as our chosen font icon family
+/// Used by @mixin icons()
+/// @author Damon Cook
+/// @group fontawesomeicons
+/// @see icons
 
-// Map icon names to font unicode characters
-// see @mixin in _icon-font-awesome.scss
-//
-// Example usage:
-//
-//    .menu-toggle {
-//        @include icon(before, favicon) {
-//            padding-left: 3px;
-//        }
-//    }
+$font-icon: "FontAwesome";
+
+
+/// Map icon names to font unicode characters
+///
+/// @example scss - Basic Usage
+///
+///    .menu-toggle {
+///        @include icon(before, navicon) {
+///           padding-left: 3px;
+///       }
+///   }
+///
+/// @group fontawesomeicons
+/// @see icons
 
 $icons: (