feat(generators/app/templates): add support for easy access to genera…

…ted code documentation

README.md

@@ -195,6 +195,15 @@ command           | description
 `grunt --help`    | will show you all of the above and the kitchen sink;
 
 
+### Documentation
+
+For both building and then launching the code documentation in your browser, BAT also supplies this convenient shortcut:
+
+```bash
+npm run doc
+```
+
+
 ### Unit tests
 
 BAT comes with support for unit testing using [Karma](http://karma-runner.github.io/1.0/), [Jasmine](http://jasmine.github.io/2.4/introduction.html) and [PhantomJS](http://phantomjs.org/).

generators/app/index.js

@@ -714,6 +714,7 @@ class AppGenerator extends Generator
                 ,   'browserify-shim'
                 ,   'coffeeify@<3'
                 ,   'coffee-script@<2'
+                ,   'glob'
                 ,   'grunt'
                 ,   'grunt-browserify'
                 ,   'grunt-coffee-jshint@<2'

generators/app/templates/@Gruntfile.coffee

@@ -142,6 +142,7 @@
 'use strict'
 
 child_process   = require( 'child_process' )
+glob            = require( 'glob' )
 path            = require( 'path' )
 _               = require( 'underscore' )
 
@@ -1064,6 +1065,11 @@ module.exports = ( grunt ) ->
                     linkNatives:        true
                     tabtospace:         4
 
+                    ##              NOTE:   The list of YUIDoc documentation sets, as bundled with installed packages will be dynamically established
+                    ##                      when the 'doc' task is run.
+                    ##
+                    external:           {}
+
     )
 
 
@@ -1191,6 +1197,46 @@ module.exports = ( grunt ) ->
 
             ##
 
+            ##  Include any installed npm dependencies with bundled YUIDoc documentation, signalled by the presence of a `data.json` and some duck typing.
+            ##
+            externals =
+                glob
+                    .sync(
+                        "node_modules/@(#{
+                            Object
+                                ##  Names of installed `dependencies`.
+                                ##
+                                .keys( grunt.config( 'npm.installed' ))
+                                ##
+                                ##  Escaped for use in this glob expression.
+                                ##
+                                .map( ( name ) -> name.replace( /[!()*+?@\[\]^{|}]/g, '\\$&' ) )
+                                .join( '|' )
+                        })/**/data.json"
+                    )
+                    .filter( ( path ) ->
+
+                        data = grunt.file.readJSON( path )
+
+                        ##  Does it walk like a duck?
+                        ##
+                        for prop in [ 'project', 'files', 'modules', 'classes', 'elements', 'classitems', 'warnings' ]
+                            return false unless data[ prop ]
+
+                        return true
+
+                    )
+                    .map( ( path ) ->
+
+                        base:   "/#{ path.slice( 0, -( 'data.json'.length )) }"
+                        json:   path
+                    )
+
+
+            grunt.config( 'yuidoc.app.options.external', data: externals ) if externals.length
+
+            ##
+
             grunt.task.run(
                 'clean:doc'
                 'yuidoc:app'

generators/app/templates/@README.md

@@ -79,6 +79,18 @@ command           | description
 `grunt --help`    | will show you all of the above and the kitchen sink;
 
 
+### Document
+
+Code documentation is generated from [comments in your source code](http://yui.github.io/yuidoc/syntax/index.html) using
+[YUIDoc](http://yui.github.io/yuidoc/).
+
+To easily access the generated code documentation, do:
+
+```bash
+npm run doc
+```
+
+
 ### Test
 
 Unit testing is an integrated build step in both `dist` and `debug` build runs, but can also be run independently as:

generators/app/templates/@package.json

@@ -55,6 +55,7 @@
   "repository": {},
   "scripts": {
     "build": "command -v grunt > /dev/null || { echo >&2 'It appears that \"grunt\" is not installed.  Consider running \"[sudo ]npm install -g grunt-cli\" first.'; exit ; } && grunt --no-color ${npm_config_debug+debug} ${npm_config_target+\"--target=${npm_config_target}\"}",
+    "doc": "grunt doc && { { sleep 3; \"${npm_config_browser}\" http://localhost:8080/dist/doc ; } & npx http-server ; }",
     "dist": "true",
     "prebuild": "rm -rf \"${npm_package_config_dist}\"",
     "predist": "npm run build",