Merge pull request #158 from cferdinandi/development

v4.2.0

README.md

@@ -16,8 +16,10 @@ Kraken is free to use under the [MIT License](http://gomakethings.com/mit/).
 
 Kraken uses [semantic versioning](http://semver.org/).
 
-* v4.2.0 - October 15, 2014
+* v4.2.0 - October 16, 2014
     * Updated Gulp task naming convention for better readability (action:object).
+    * Added `gulp watch` and `gulp reload` task runners (regular and docs flavored).
+    * Reorganized `package.json` and `gulpfile.js` packages.
 * v4.1.2 - October 15, 2014
     * Updated `gulp-svgstore` to version `2.x`.
     * Replaced `gulp-clean` with native Node `del` method.

docs/generating-documentation.html

@@ -36,7 +36,7 @@
 
 		<h1>Generating Documentation</h1>
 
-		<p>Kraken ships with a simple documentation generator powered by <a href="http://gulpjs.com">Gulp.js</a>. Unfortunately, if you're uncomfortable using terminal, you won't be able to take advantage of this feature.</p>
+		<p>Kraken ships with a simple documentation generator powered by <a href="http://gulpjs.com">Gulp.js</a>. This feature requires you to <a href="working-with-the-source-files.html">work with the source files</a>.</p>
 
 		<p>Documentation files can be found under <code>src</code> > <code>docs</code>, and compile to <code>docs</code>.</p>
 
@@ -54,7 +54,12 @@ <h2 id="how-to-create-docs">How to Create Docs</h2>
 
 		<p>Files placed in the <code>assets</code> directory will be moved over as-is to the <code>docs</code> directory. Kraken will also add a copy of your <code>dist</code> files so you can use them in your documentation.</p>
 
-		<p>When you're ready, run <code>gulp docs</code> in terminal.</p>
+		<p class="space-bottom-small">When you're ready, run one of the task runners to get going:</p>
+		<ul>
+			<li><code>gulp docs</code> manually compiles files and generates docs.</li>
+			<li><code>gulp watch:docs</code> automatically compiles files and generates docs when changes are made.</li>
+			<li><code>gulp reload:docs</code> automatically compiles files, generates docs, and applies changes using <a href="http://livereload.com/">LiveReload</a>.</li>
+		</ul>
 
 
 		<h2 id="why-not-use-an-existing-documentation-tool">Why not use an existing documentation tool?</h2>

docs/working-with-the-source-files.html

@@ -67,10 +67,17 @@ <h2 id="quick-start">Quick Start</h2>
 		<ol>
 			<li>In bash/terminal/command line, <code>cd</code> into the <code>kraken</code> directory.</li>
 			<li>Run <code>npm install</code> to install the required files.</li>
-			<li>When it's done installing, run <code>gulp</code> to get going.</li>
+			<li>
+				When it's done installing, run one of the task runners to get going:
+				<ul>
+					<li><code>gulp</code> manually compiles files.</li>
+					<li><code>gulp watch</code> automatically compiles files when changes are made.</li>
+					<li><code>gulp reload</code> automatically compiles files and applies changes using <a href="http://livereload.com/">LiveReload</a>.</li>
+				</ul>
+			</li>
 		</ol>
 
-		<p>Every time you make changes, run <code>gulp</code> to process them.</p>
+		<!-- <strong>Gulp Task Runners</strong> -->
 
 
 		<h2 id="working-with-sass">Working with Sass</h2>

gulpfile.js

@@ -2,36 +2,48 @@
  * Gulp Packages
  */
 
+// General
 var gulp = require('gulp');
 var fs = require('fs');
-var plumber = require('gulp-plumber');
 var del = require('del');
 var lazypipe = require('lazypipe');
-var rename = require('gulp-rename');
+var plumber = require('gulp-plumber');
 var flatten = require('gulp-flatten');
 var tap = require('gulp-tap');
+var rename = require('gulp-rename');
 var header = require('gulp-header');
 var footer = require('gulp-footer');
+var watch = require('gulp-watch');
+var livereload = require('gulp-livereload');
+var package = require('./package.json');
+
+// Scripts and tests
 var jshint = require('gulp-jshint');
 var stylish = require('jshint-stylish');
 var concat = require('gulp-concat');
 var uglify = require('gulp-uglify');
+var karma = require('gulp-karma');
+
+// Styles
 var sass = require('gulp-ruby-sass');
 var prefix = require('gulp-autoprefixer');
 var minify = require('gulp-minify-css');
-var karma = require('gulp-karma');
+
+// SVGs
 var svgmin = require('gulp-svgmin');
 var svgstore = require('gulp-svgstore');
+
+// Docs
 var markdown = require('gulp-markdown');
 var fileinclude = require('gulp-file-include');
-var package = require('./package.json');
 
 
 /**
  * Paths to project folders
  */
 
 var paths = {
+	input: 'src/**/*',
 	output: 'dist/',
 	scripts: {
 		input: 'src/js/*',
@@ -156,7 +168,7 @@ gulp.task('lint:scripts', function () {
 
 // Remove prexisting content from output and test folders
 gulp.task('clean:dist', function () {
-	return del.sync([
+	del.sync([
 		paths.output,
 		paths.test.coverage,
 		paths.test.results
@@ -208,6 +220,48 @@ gulp.task('clean:docs', function () {
 	return del.sync(paths.docs.output);
 });
 
+// Watch for changes to files
+gulp.task('listen', function () {
+	watch(paths.input, function (files) {
+		gulp.start('default');
+	});
+});
+
+// Watch for changes to files and docs
+gulp.task('listen:docs', function () {
+	watch(paths.input, function (files) {
+		gulp.start('docs');
+	});
+});
+
+// Spin up livereload server and listen for file changes
+gulp.task('server', function () {
+	livereload.listen();
+	watch(paths.input, function (files) {
+		gulp.start('default');
+		gulp.start('refresh');
+	});
+});
+
+// Spin up livereload server and listen for file and documentation changes
+gulp.task('server:docs', function () {
+	livereload.listen();
+	watch(paths.input, function (files) {
+		gulp.start('docs');
+		gulp.start('refresh:docs');
+	});
+});
+
+// Run livereload after file change
+gulp.task('refresh', ['default'], function () {
+	livereload.changed();
+});
+
+// Run livereload after file or documentation change
+gulp.task('refresh:docs', ['docs'], function () {
+	livereload.changed();
+});
+
 
 /**
  * Task Runners
@@ -231,4 +285,28 @@ gulp.task('docs', [
 	'build:docs',
 	'copy:dist',
 	'copy:assets'
+]);
+
+// Compile files when something changes
+gulp.task('watch', [
+	'listen',
+	'default'
+]);
+
+// Compile files and generate docs when something changes
+gulp.task('watch:docs', [
+	'listen:docs',
+	'docs'
+]);
+
+// Compile files and livereload pages when something changes
+gulp.task('reload', [
+	'server',
+	'default'
+]);
+
+// Compile files, generate docs, and livereload pages when something changes
+gulp.task('reload:docs', [
+	'server:docs',
+	'docs'
 ]);

package.json

@@ -14,32 +14,33 @@
 	},
 	"devDependencies": {
 		"gulp": "^3.8.0",
-		"gulp-autoprefixer": "^0.0.7",
-		"gulp-concat": "^2.2.0",
+		"node-fs": "^0.1.7",
+		"del": "^0.1.3",
+		"lazypipe": "^0.2.2",
+		"gulp-plumber": "^0.6.2",
 		"gulp-flatten": "^0.0.2",
 		"gulp-tap": "^0.1.1",
+		"gulp-rename": "^1.1.0",
 		"gulp-header": "^1.1.1",
 		"gulp-footer": "^1.0.5",
+		"gulp-watch": "^1.1.0",
+		"gulp-livereload": "^2.1.1",
 		"gulp-jshint": "^1.6.1",
-		"gulp-karma": "^0.0.4",
-		"gulp-minify-css": "^0.3.4",
-		"gulp-plumber": "^0.6.2",
-		"gulp-rename": "^1.1.0",
-		"gulp-ruby-sass": "^0.7.1",
-		"gulp-uglify": "^0.3.0",
-		"gulp-svgmin": "^0.4.6",
-		"gulp-svgstore": "^2.0.0",
-		"gulp-markdown": "^1.0.0",
-		"gulp-file-include": "^0.5.1",
 		"jshint-stylish": "^0.2.0",
-		"node-fs": "^0.1.7",
-		"del": "^0.1.3",
-		"lazypipe": "^0.2.2",
-		"karma": "^0.12.16",
+		"gulp-concat": "^2.2.0",
+		"gulp-uglify": "^0.3.0",
+		"gulp-karma": "^0.0.4",
 		"karma-coverage": "^0.2.4",
 		"karma-jasmine": "^0.2.0",
 		"karma-phantomjs-launcher": "^0.1.4",
 		"karma-spec-reporter": "^0.0.13",
-		"karma-htmlfile-reporter": "^0.1"
+		"karma-htmlfile-reporter": "^0.1",
+		"gulp-ruby-sass": "^0.7.1",
+		"gulp-minify-css": "^0.3.4",
+		"gulp-autoprefixer": "^0.0.7",
+		"gulp-svgmin": "^0.4.6",
+		"gulp-svgstore": "^2.0.0",
+		"gulp-markdown": "^1.0.0",
+		"gulp-file-include": "^0.5.1"
 	}
 }

src/docs/generating-documentation.html

@@ -3,7 +3,7 @@
 
 		<h1>Generating Documentation</h1>
 
-		<p>Kraken ships with a simple documentation generator powered by <a href="http://gulpjs.com">Gulp.js</a>. Unfortunately, if you're uncomfortable using terminal, you won't be able to take advantage of this feature.</p>
+		<p>Kraken ships with a simple documentation generator powered by <a href="http://gulpjs.com">Gulp.js</a>. This feature requires you to <a href="working-with-the-source-files.html">work with the source files</a>.</p>
 
 		<p>Documentation files can be found under <code>src</code> > <code>docs</code>, and compile to <code>docs</code>.</p>
 
@@ -21,7 +21,12 @@ <h2 id="how-to-create-docs">How to Create Docs</h2>
 
 		<p>Files placed in the <code>assets</code> directory will be moved over as-is to the <code>docs</code> directory. Kraken will also add a copy of your <code>dist</code> files so you can use them in your documentation.</p>
 
-		<p>When you're ready, run <code>gulp docs</code> in terminal.</p>
+		<p class="space-bottom-small">When you're ready, run one of the task runners to get going:</p>
+		<ul>
+			<li><code>gulp docs</code> manually compiles files and generates docs.</li>
+			<li><code>gulp watch:docs</code> automatically compiles files and generates docs when changes are made.</li>
+			<li><code>gulp reload:docs</code> automatically compiles files, generates docs, and applies changes using <a href="http://livereload.com/">LiveReload</a>.</li>
+		</ul>
 
 
 		<h2 id="why-not-use-an-existing-documentation-tool">Why not use an existing documentation tool?</h2>

src/docs/working-with-the-source-files.html

@@ -34,10 +34,17 @@ <h2 id="quick-start">Quick Start</h2>
 		<ol>
 			<li>In bash/terminal/command line, <code>cd</code> into the <code>kraken</code> directory.</li>
 			<li>Run <code>npm install</code> to install the required files.</li>
-			<li>When it's done installing, run <code>gulp</code> to get going.</li>
+			<li>
+				When it's done installing, run one of the task runners to get going:
+				<ul>
+					<li><code>gulp</code> manually compiles files.</li>
+					<li><code>gulp watch</code> automatically compiles files when changes are made.</li>
+					<li><code>gulp reload</code> automatically compiles files and applies changes using <a href="http://livereload.com/">LiveReload</a>.</li>
+				</ul>
+			</li>
 		</ol>
 
-		<p>Every time you make changes, run <code>gulp</code> to process them.</p>
+		<!-- <strong>Gulp Task Runners</strong> -->
 
 
 		<h2 id="working-with-sass">Working with Sass</h2>