Merge pull request #16 from cferdinandi/development

v1.1.0

STARTER-README.md → README-TEMPLATE.md

@@ -1,39 +1,39 @@
 # NAMESPACE-UP [![Build Status](https://travis-ci.org/GITHUB-USERNAME/NAMESPACE-LOW.svg)](https://travis-ci.org/GITHUB-USERNAME/NAMESPACE-LOW)
 DESCRIPTION.
 
-[Download NAMESPACE-UP](https://github.com/GITHUB-USERNAME/NAMESPACE-LOW/archive/master.zip) / [View the demo](http://GITHUB-USERNAME.github.io/NAMESPACE-LOW/).
+[Download NAMESPACE-UP](https://github.com/GITHUB-USERNAME/NAMESPACE-LOW/archive/master.zip) / [View the demo](http://GITHUB-USERNAME.github.io/NAMESPACE-LOW/)
 
 **In This Documentation**
 
 1. [Getting Started](#getting-started)
 2. [Installing with Package Managers](#installing-with-package-managers)
-3. [Options & Settings](#options-and-settings)
-4. [Browser Compatibility](#browser-compatibility)
-5. [How to Contribute](#how-to-contribute)
-6. [License](#license)
-7. [Changelog](#changelog)
-8. [Older Docs](#older-docs)
+3. [Working with the Source Files](#working-with-the-source-files)
+4. [Options & Settings](#options-and-settings)
+5. [Browser Compatibility](#browser-compatibility)
+6. [How to Contribute](#how-to-contribute)
+7. [License](#license)
+8. [Changelog](#changelog)
+9. [Older Docs](#older-docs)
 
 
 
 ## Getting Started
 
-Compiled and production-ready code can be found in the `dist` directory. The `src` directory contains development code. Unit tests are located in the `test` directory.
+Compiled and production-ready code can be found in the `dist` directory. The `src` directory contains development code. Unit tests are located in the `test` directory. It's the same build system that's used by [Kraken](http://cferdinandi.github.io/kraken/), so it includes some unnecessary tasks and Sass variables but can be dropped right in to the boilerplate without any configuration.
 
 ### 1. Include NAMESPACE-UP on your site.
 
 ```html
 <link rel="stylesheet" href="dist/css/NAMESPACE-LOW.css">
 <script src="dist/js/classList.js"></script>
-<script src="dist/js/bind-polyfill.js"></script>
 <script src="dist/js/NAMESPACE-LOW.js"></script>
 ```
 
 NAMESPACE-UP is [built with Sass](http://sass-lang.com/) for easy customization. If you don't use Sass, that's ok. The `css` folder contains compiled vanilla CSS.
 
 The `_config.scss` and `_mixins.scss` files are the same ones used in [Kraken](http://GITHUB-USERNAME.github.io/kraken/), so you can drop the `_NAMESPACE-LOW.css` file right into Kraken without making any updates. Or, adjust the variables to suit your own project.
 
-NAMESPACE-UP also requires [classList.js](https://github.com/eligrey/classList.js) and `bind-polyfill.js`, polyfills that extend ECMAScript 5 API support to more browsers.
+NAMESPACE-UP also requires [classList.js](https://github.com/eligrey/classList.js), a polyfill that extends ECMAScript 5 API support to more browsers.
 
 ### 2. Add the markup to your HTML.
 
@@ -65,6 +65,28 @@ You can install NAMEPSACE-UP with your favorite package manager.
 
 
 
+## Working with the Source Files
+
+If you would prefer, you can work with the development code in the `src` directory using the included [Gulp build system](http://gulpjs.com/). This compiles, lints, and minifies code, and runs unit tests. It's the same build system that's used by [Kraken](http://cferdinandi.github.io/kraken/), so it includes some unnecessary tasks and Sass variables but can be dropped right in to the boilerplate without any configuration.
+
+### Dependencies
+Make sure these are installed first.
+
+* [Node.js](http://nodejs.org)
+* [Ruby Sass](http://sass-lang.com/install)
+* [Gulp](http://gulpjs.com) `sudo npm install -g gulp`
+
+### Quick Start
+
+1. In bash/terminal/command line, `cd` into your project directory.
+2. Run `npm install` to install required files.
+3. When it's done installing, run one of the task runners to get going:
+	* `gulp` manually compiles files.
+	* `gulp watch` automatically compiles files when changes are made.
+	* `gulp reload` automatically compiles files and applies changes using [LiveReload](http://livereload.com/).
+
+
+
 ## Options and Settings
 
 NAMESPACE-UP includes smart defaults and works right out of the box. But if you want to customize things, it also has a robust API that provides multiple ways for you to adjust the default options and settings.
@@ -103,7 +125,7 @@ Description
 ```
 
 #### destroy()
-Destroy the current `NAMESPACE-LOW.init()`.
+Destroy the current `NAMESPACE-LOW.init()`. This is called automatically during the init function to remove any existing initializations.
 
 ```javascript
 NAMESPACE-LOW.destroy();

README.md

@@ -1,12 +1,13 @@
 # Gulp Boilerplate [![Build Status](https://travis-ci.org/cferdinandi/gulp-boilerplate.svg)](https://travis-ci.org/cferdinandi/gulp-boilerplate)
 
-My boilerplate for creating new web projects with [Gulp.js](http://gulpjs.com/). Forked from [Todd Motto's GulpOSS](https://github.com/toddmotto/gulp-oss) with some additions from [Mark Goodyear and Big Bite Creative](https://github.com/bigbitecreative/base).
+My boilerplate for creating new web projects with [Gulp.js](http://gulpjs.com/). Forked from [Todd Motto's GulpOSS](https://github.com/toddmotto/gulp-oss) with some additions from [Mark Goodyear and Big Bite Creative](https://github.com/bigbitecreative/base) and various tutorials around the web.
 
 * Lints and concatenates JS files.
 * Compiles Sass files and automatically [adds vendor prefixes](https://github.com/ai/autoprefixer).
-* Exports both minified and expanded JS and CSS files.
+* Exports both minified and expanded JS and CSS files with header info.
+* Generates SVG sprites.
+* Generates documentation.
 * Cleans up file directories.
-* Adds a header to the top of all JS and CSS files.
 * Runs Jasmine unit tests and generates reports.
 * Includes a `.travis.yml` file for continuous integration with [TravisCI](https://travis-ci.org).
 
@@ -15,10 +16,12 @@ My boilerplate for creating new web projects with [Gulp.js](http://gulpjs.com/).
 **In This Documentation**
 
 1. [Getting Started](#getting-started)
-2. [Options & Settings](#options-and-settings)
-3. [Unit Testing](#unit-testing)
-3. [License](#license)
-4. [Changelog](#changelog)
+2. [File Structure](#file-structure)
+3. [Working with the Source Files](#working-with-the-source-files)
+4. [Options & Settings](#options-and-settings)
+5. [Continuous Integration](#continuous-integration)
+6. [License](#license)
+7. [Changelog](#changelog)
 
 ## Getting Started
 
@@ -28,19 +31,28 @@ Make sure these are installed first.
 * [Node.js](http://nodejs.org)
 * [Ruby Sass](http://sass-lang.com/install)
 * [Gulp](http://gulpjs.com) `sudo npm install -g gulp`
-* [PhantomJS](http://phantomjs.org)
 
 ### Quick Start
 
 1. In bash/terminal/command line, `cd` into your project directory.
 2. Run `npm install` to install required files.
-3. When it's done installing, run `gulp` to get going.
+3. When it's done installing, run one of the task runners to get going:
+	* `gulp` manually compiles files.
+	* `gulp docs` manually compiles files and generates documentation.
+	* `gulp watch` automatically compiles files when changes are made.
+	* `gulp watch:docs` automatically compiles files and geneates docs when changes are made.
+	* `gulp reload` automatically compiles files and applies changes using [LiveReload](http://livereload.com/).
+	* `gulp reload:docs` automatically compiles files, generates docs, and applies changes using [LiveReload](http://livereload.com/).
 
-Every time you want to run your tasks, run `gulp`.
 
-### File Structure
 
-Add your files to the appropriate `src` subdirectories. Gulp will process and and compile them into `dist`. Content in subdirectories under the `js` folder will be concatenated. (For example, files in `js/detects` will compile into `detects.js`.) Files directly under `js` will compile individually.
+## File Structure
+
+Add your files to the appropriate `src` subdirectories. Gulp will process and and compile them into `dist`.
+
+* Content in subdirectories under the `js` folder will be concatenated. For example, files in `js/detects` will compile into `detects.js`. Files directly under `js` will compile individually.
+* SVGs in the `svg` directory will compile into `icons.svg`.
+* Assets in the `assets` directory will be copied as-is into the `dist` directory.
 
 ```
 gulp-boilerplate/
@@ -49,20 +61,29 @@ gulp-boilerplate/
 |   |   |—— myplugin.css
 |   |   |—— myplugin.min.css
 |   |—— js/
-|   |   |—— bind-polyfill.js
-|   |   |—— bind-polyfill.min.js
 |   |   |—— classList.js
 |   |   |—— classList.min.js
 |   |   |—— myplugin.js
 |   |   |—— myplugin.min.js
+|   |—— svg/
+|   |   |—— icons.svg
 |   |—— # static assets
+|—— docs/
+|   |—— assets/
+|   |—— dist/
+|   |—— index.html
+|   |—— # other docs
 |—— src/
 |   |—— js/
-|   |   |—— bind-polyfill.js
 |   |   |—— classList.js
 |   |   |—— myplugin.js
 |   |—— sass/
-|   |   |—— myplugin.sass
+|   |   |—— _config.scss
+|   |   |—— _mixins.scss
+|   |   |—— components/
+|   |   |   |—— myplugin.scss
+|   |—— svg/
+|   |   |—— # svgs
 |   |—— static/
 |   |   |—— # static assets
 |—— test/
@@ -77,11 +98,35 @@ gulp-boilerplate/
 |—— index.html
 |—— package.json
 |—— README.md
-|—— STARTER-README.md
+|—— README-TEMPLATE.md
 ```
 
 
 
+## Working with the Source Files
+
+### Sass
+
+Sass files are located in `src` > `sass`. Gulp generates minified and unminified CSS files. It also includes [autoprefixer](https://github.com/postcss/autoprefixer), which adds vendor prefixes for you if required by the last two versions of a browser.
+
+### JavaScript
+
+JavaScript files are located in the `src` > `js` directory.
+
+Files placed directly in the js folder will compile directly to `dist` > `js` as both minified and unminified files. Files placed in subdirectories will also be concatenated into a single file. For example, files in `js/detects` will compile into `detects.js`. Files directly under `js` will compile individually.
+
+#### Unit Testing
+
+Gulp Boilerplate is set up for unit testing with [Jasmine](http://jasmine.github.io/2.0/introduction.html). Add your tests to `test/spec/spec-myplugin.js`. Adjust filenames and references as needed.
+
+Unit test results are printed in terminal, but you can also view them in a browser under `test/results/unit-tests.html`. Get a report of how much of your scripts is covered by testing under `test/coverage`.
+
+### SVGs
+
+SVG files placed in the `src` > `svg` directory will be compiled into a single SVG sprite called `icons.svg` in the `dist` > `svg` directory.
+
+
+
 ## Options and Settings
 
 ### Updating Project Details
@@ -95,30 +140,47 @@ Inside `gulpfile.js` you'll see a variable named `paths`. Adjust the paths to su
 
 ```js
 var paths = {
-    output : 'dist/',
-    scripts : {
-        input : [ 'src/js/*' ],
-        output : 'dist/js/'
-    },
-    styles : {
-        input : 'src/sass/**/*.scss',
-        output : 'dist/css/'
-    },
-    static : 'src/static/**',
-    test : {
-        spec : [ 'test/spec/**/*.js' ],
-        coverage: 'test/coverage/',
-        results: 'test/results/'
-    }
+	input: 'src/**/*',
+	output: 'dist/',
+	scripts: {
+		input: 'src/js/*',
+		output: 'dist/js/'
+	},
+	styles: {
+		input: 'src/sass/**/*.{scss,sass}',
+		output: 'dist/css/'
+	},
+	svgs: {
+		input: 'src/svg/**/*.svg',
+		output: 'dist/svg/'
+	},
+	static: 'src/static/**',
+	test: {
+		input: 'src/js/**/*.js',
+		karma: 'test/karma.conf.js',
+		spec: 'test/spec/**/*.js',
+		coverage: 'test/coverage/',
+		results: 'test/results/'
+	},
+	docs: {
+		input: 'src/docs/*.{html,md,markdown}',
+		output: 'docs/',
+		templates: 'src/docs/_templates/',
+		assets: 'src/docs/assets/**'
+	}
 };
 ```
 
 
-## Unit Testing
 
-Gulp Boilerplate is set up for unit testing with [Jasmine](http://jasmine.github.io/2.0/introduction.html). Add your tests to `test/spec/spec-myplugin.js`. Adjust filenames and references as needed.
+## Continuous Integration
+
+This boilerplate includes a configuration file for [Travis CI](http://docs.travis-ci.com/user/getting-started/), a continuous integration service for GitHub.
+
+If you sign-up and activate it for your repository, Travis CI will run your build and execute any processes to make sure everything is working as expected. This is particularly useful when working with a team or managing open source projects with multiple contributors.
+
+The `.travis.yml` file is pre-configured for the boilerplate's build system. Even if you add files or update the Gulp tasks, you shouldn't need to change anything for it to work.
 
-Unit test results are printed in terminal, but you can also view them in a browser under `test/results/unit-tests.html`. Get a report of how much of your scripts is covered by testing under `test/coverage`.
 
 
 ## License
@@ -131,6 +193,12 @@ Gulp Boilerplate is licensed under the [MIT License](http://gomakethings.com/mit
 
 Gulp Boilerplate uses [semantic versioning](http://semver.org/).
 
+* v1.1.0 - October 18, 2014
+	* Added documentation generator.
+	* Added SVG sprite generator.
+	* Added LiveReload and change watching tasks.
+	* Renamed Gulp tasks for better semantics.
+	* Updated docs.
 * v1.0.2 - October 2, 2014
     * Added CommonJS bug fix.
     * Updated readme.md to reflect new file structure.

dist/css/myplugin.css

@@ -1,10 +1,9 @@
 /**
- * gulp-boilerplate v1.0.2
+ * gulp-boilerplate v1.1.0
  * My Gulp.js boilerplate for creating new web projects, by Chris Ferdinandi.
  * http://github.com/cferdinandi/Plugin
  * 
  * Free to use under the MIT License.
  * http://gomakethings.com/mit/
  */
 
-/* Your content here... */

dist/css/myplugin.min.css

@@ -1 +1 @@
-/** gulp-boilerplate v1.0.2, by Chris Ferdinandi | http://github.com/cferdinandi/Plugin | Licensed under MIT: http://gomakethings.com/mit/ */
+/** gulp-boilerplate v1.1.0, by Chris Ferdinandi | http://github.com/cferdinandi/Plugin | Licensed under MIT: http://gomakethings.com/mit/ */

dist/js/classList.js

@@ -1,5 +1,5 @@
 /**
- * gulp-boilerplate v1.0.2
+ * gulp-boilerplate v1.1.0
  * My Gulp.js boilerplate for creating new web projects, by Chris Ferdinandi.
  * http://github.com/cferdinandi/Plugin
  * 

dist/js/myplugin.js

@@ -1,5 +1,5 @@
 /**
- * gulp-boilerplate v1.0.2
+ * gulp-boilerplate v1.1.0
  * My Gulp.js boilerplate for creating new web projects, by Chris Ferdinandi.
  * http://github.com/cferdinandi/Plugin
  *