Documentation (#42)

* Organization and cleanup * Moved sassdoc dest to docs from sassdoc * document breakpoints and neat grid media queries * Removed base from sassdoc * Split up the groups in to more groups * Group example * Moar documentation * rename and document _color to _colors (for color map) * Document set container padding * Add import to color_theme so that required variables are there * fixup! WIP * organize variables * Merge conflict fixes * !fixup source order conflicts * !fixup leading commas on rollup
SU-SWS · Apr 20, 2017 · 4bff9cc · 4bff9cc
1 parent a5f992d
commit 4bff9cc
Show file tree

Hide file tree

Showing 166 changed files with 4,117 additions and 512 deletions.
diff --git a/Gruntfile.js b/Gruntfile.js
@@ -15,10 +15,142 @@ module.exports = function(grunt) {
       },
       target: ['core/\*\*/\*.scss']
     },
+    // Examples: https://github.com/SassDoc/grunt-sassdoc/blob/master/Gruntfile.js
     sassdoc: {
       default: {
         src: 'core',
-      }
+        options: {
+          dest: 'docs/core',
+          verbose: 0,
+          autofill: ['requires', 'throws'],
+          exclude: [
+            'vendors/*',
+            'base/*'
+          ],
+          display: {
+            sort: [
+              'group<',
+              'access',
+              'line>',
+              'file',
+            ],
+          },
+        },
+      },
+      base: {
+        src: 'core/base',
+        options: {
+          dest: 'docs/base',
+          verbose: 0,
+          autofill: ['requires', 'throws'],
+          display: {
+            sort: [
+              'group<',
+              'access',
+              'line>',
+              'file',
+            ],
+          },
+          groups: {
+            'base|typography': 'Typography',
+          },
+        },
+      },
+      components: {
+        src: 'core/components',
+        options: {
+          dest: 'docs/components',
+          verbose: 0,
+          autofill: ['requires', 'throws'],
+          display: {
+            sort: [
+              'group<',
+              'access',
+              'line>',
+              'file',
+            ],
+          },
+        },
+      },
+      functions: {
+        src: 'core/utilities/functions',
+        options: {
+          dest: 'docs/functions',
+          verbose: 0,
+          autofill: ['requires', 'throws'],
+          display: {
+            sort: [
+              'group<',
+              'access',
+              'line>',
+              'file',
+            ],
+          },
+        },
+      },
+      mixins: {
+        src: 'core/utilities/mixins',
+        options: {
+          dest: 'docs/mixins',
+          verbose: 0,
+          autofill: ['requires', 'throws'],
+          display: {
+            sort: [
+              'group<',
+              'access',
+              'line>',
+              'file',
+            ],
+          },
+        },
+      },
+      placeholders: {
+        src: 'core/utilities/placeholders',
+        options: {
+          dest: 'docs/placeholders',
+          verbose: 0,
+          autofill: ['requires', 'throws'],
+          display: {
+            sort: [
+              'group<',
+              'access',
+              'line>',
+              'file',
+            ],
+          },
+        },
+      },
+      variables: {
+        src: 'core/utilities/variables',
+        options: {
+          dest: 'docs/variables',
+          verbose: 0,
+          autofill: ['requires', 'throws'],
+          display: {
+            sort: [
+              'group<',
+              'access',
+              'line>',
+              'file',
+            ],
+          },
+          groups: {
+            'variables|bourbon': 'Bourbon Settings',
+            'variables|neat': 'Neat Settings',
+            'variables|decanter': 'Decanter Settings',
+            'variables|animations': 'Animations',
+            'variables|borders': 'Borders',
+            'variables|breakpoint-boundaries': 'Breakpoints',
+            'variables|grid-media': 'Grid Media',
+            'variables|buttons': 'Buttons',
+            'variables|colors': 'Colors',
+            'variables|containers': 'Containers',
+            'variables|forms': 'Forms',
+            'variables|typography': 'Typography',
+            'variables|vertical-rhythm': 'Vertical Rhythm',
+          },
+        },
+      },
     },
     sass: {
       // This will compile all of our sass files
@@ -94,7 +226,7 @@ module.exports = function(grunt) {
           'examples/**/*.scss',
           'examples/**/*.html'
         ],
-        tasks: ['sass'],
+        tasks: ['sass', 'sassdoc'],
         options: {
           interrupt: true
         }

diff --git a/core/base/_body.scss b/core/base/_body.scss
@@ -2,8 +2,13 @@
 
 ////
 /// Root html element styles for the body and main elements.
+/// Style placement and basic settings for the top level html elements.
+/// @group base|body
 ////
 
+///
+/// Body defaults
+///
 body {
   min-height: 100vh;
   display: flex;
@@ -12,20 +17,26 @@ body {
   margin: 0;
 }
 
-// We rely on source order for mobile-first approach
-// in this case:
-//
-//  -50   header
-//  -40   nav
-//    1   main
-//   50   footer
-//
-
+/// We rely on source order for mobile-first approach
+/// in this case:
+///
+///  -50   header
+///  -40   nav
+///    1   main
+///   50   footer
+///
 body > header { order: -50; }
+
+/// Nav html element.
 body > nav { order: -40; }
+
+/// Main html element of body.
 body > main { order: 1; }
+
+// footer html element of body.
 body > footer { order: 50; }
 
+/// Main html element.
 main {
   overflow: hidden;
   background-color: color(background);

diff --git a/core/base/_box-model.scss b/core/base/_box-model.scss
@@ -2,28 +2,29 @@
 
 ////
 /// Box model default styles.
-/// @group html
+/// @group base|box-model
 ////
 
-// @import '../utilities/settings/settings';
+/// Set up a decent box model on the root element.
 
-// Set up a decent box model on the root element.
 html {
   font-size: 62.5%; // 1rem = 10px;
   box-sizing: border-box;
 }
 
-// Make all elements from the DOM inherit from the parent box-sizing
-// Since `*` has a specificity of 0, it does not override the `html` value
-// making all elements inheriting from the root box-sizing value
-// See: https://css-tricks.com/inheriting-box-sizing-probably-slightly-better-best-practice/
+/// Make all elements from the DOM inherit from the parent box-sizing
+/// Since `*` has a specificity of 0, it does not override the `html` value
+/// making all elements inheriting from the root box-sizing value
+/// See: https://css-tricks.com/inheriting-box-sizing-probably-slightly-better-best-practice/
+
 *, *::before, *::after {
   box-sizing: inherit;
 }
 
 /// Set the base body font size.
 /// @require {function} em Relative unit function
 /// @require {variable} $base-font-size Base font size
+
 body {
   @include font-size($base-font-size, $root-font-size);
 }
diff --git a/core/base/_buttons.scss b/core/base/_buttons.scss
@@ -2,11 +2,9 @@
 
 ////
 /// Button base styles.
-/// @group base
+/// @group base|buttons
 ////
 
-// @import '../utilities/utilities';
-
 /// Generic Button Styles.
 /// @require {function} color Returns a color from the color map.
 /// @require {function} em normalized relative values.

diff --git a/core/base/_fonts.scss b/core/base/_fonts.scss
@@ -2,7 +2,7 @@
 ////
 /// Base font styles.
 /// This file contains all @font-face declarations, if any.
-/// @group base
+/// @group base|fonts
 ////
 
 //// Load the font-face declarations.

diff --git a/core/base/_forms.scss b/core/base/_forms.scss
@@ -1,12 +1,10 @@
 @charset "UTF-8";
 ////
 /// Form base styles.
-/// @group html
+/// @group base|forms
 ////
 
-//@import '../utilities/settings/settings';
-
-// Fieldset defaults.
+/// Fieldset defaults.
 fieldset {
   background-color: transparent;
   border: 0;
@@ -43,16 +41,15 @@ textarea {
 }
 
 /// All Text Input defaults.
+/// @require bourbon
+/// @require {function} color
+/// @require {mixin} on-event
 /// @require {variable} $base-border
 /// @require {variable} $base-border-radius
 /// @require {variable} $form-box-shadow
 /// @require {variable} $base-spacing
 /// @require {variable} $base-duration
 /// @require {variable} $base-timing
-/// @require {function} color
-/// @require {function} shade
-/// @require {function} tint
-/// @require {mixin} on-event
 /// @group base
 #{$all-text-inputs} {
   $_border: $base-border;
@@ -92,7 +89,7 @@ textarea {
   }
 }
 
-// Text area styles.
+/// Text area styles.
 textarea {
   resize: vertical;
 }

diff --git a/core/base/_lists.scss b/core/base/_lists.scss
@@ -1,28 +1,28 @@
 @charset "UTF-8";
 ////
 /// List base styles.
-/// @group html
+/// @group base|lists
 ////
 
-// @import '../utilities/settings/settings';
 
-// List classes.
+/// List classes.
 ul.plain,
 ol.plain {
   list-style-type: none;
   margin: 0;
   padding: 0;
 }
 
+/// plain
 dl.plain {
   margin: 0;
 }
-
+/// plain
 dt.plain {
   font-weight: 600;
   margin: 0;
 }
-
+/// plain
 dd.plain {
   margin: 0;
 }
@@ -38,6 +38,7 @@ ol {
   }
 }
 
+/// uls
 ul {
   list-style: disc;
   ul {
@@ -83,6 +84,7 @@ li > ol {
 dl {
   margin: 0 0 modular-scale(-5);
 }
+/// dt
 dt {
   font-weight: 600;
 }

diff --git a/core/base/_media-elements.scss b/core/base/_media-elements.scss
@@ -2,7 +2,7 @@
 
 ////
 /// Meida base styles.
-/// @group html
+/// @group base|media
 ////
 
 // @import '../utilities/settings/settings';

diff --git a/core/base/_tables.scss b/core/base/_tables.scss
@@ -1,7 +1,7 @@
 @charset "UTF-8";
 ////
 /// Media base styles.
-/// @group html
+/// @group base|tables
 ////
 
 //@import '../utilities/settings/settings';

diff --git a/core/base/_typography.scss b/core/base/_typography.scss
@@ -1,7 +1,7 @@
 @charset "UTF-8";
 ////
 /// This file contains Site-wide typography base styles.
-/// @group html
+/// @group base|typography
 ////
 
 // @import '../utilities/settings/settings';