"use strict";
/**
* @fileOverview Gruntfile tasks. These tasks are intended to help you when modifying the template. If you are
* just using the template, don't sweat this stuff. To use these tasks, you must install grunt, if you haven't already,
* and install the dependencies. All of this requires node.js, of course.
*
* Install grunt:
*
* npm install -g grunt-cli
*
* Then in the directory where you found this file:
*
* npm install
*
* And you are all set. See the individual tasks for details.
*
* @module Gruntfile
* @requires path
* @requires lodash
* @requires http
* @requires async
* @requires fs
*/
var path = require( "path" );
var _ = require( "lodash" );
var request = require('request');
var async = require( "async" );
var fs = require( "fs" );
// this rather odd arrangement of composing tasks like this to make sure this works on both
// windows and linux correctly. We can't depend on Grunt or Node to normalize
// paths for us because we shell out to make this work. So we gather up
// our relative paths here, normalize them later and then pass them into
// the shell to be run by JSDoc3.
/**
* The definition to run the development test files. This runs the files in `fixtures` with the
* project's `conf.json` file.
* @private
*/
var jsdocTestPages = {
dest : "./testdocs",
tutorials : "./fixtures/tutorials",
template : "./template",
config : "./fixtures/testdocs.conf.json",
options : " --lenient --verbose --recurse"
};
/**
* The definition to run the sample files. This runs the files in `fixtures` with the
* sample's `conf.json` file. No task directly exposes this configuration. The `fixtures` task
* modifies this for each swatch it finds and then run the docs command against it.
* @private
*/
var jsdocExamplePages = {
src : ["./fixtures/", "./README.md"],
dest : "./themes",
tutorials : "./fixtures/tutorials",
template : "./template",
config : "./fixtures/example.conf.json",
options : " --lenient --verbose --recurse"
};
/**
* This definition provides the project's main, published documentation.
* @private
*/
var projectDocs = {
src : ["./Gruntfile.js", "./README.md", "./template/publish.js"],
dest : "./dox",
tutorials : "",
template : "./template",
config : "./template/jsdoc.conf.json",
options : " --lenient --verbose --recurse --private"
};
/**
* Normalizes all paths from a JSDoc task definition and and returns an executable string that can be passed to the shell.
* @param {object} jsdoc A JSDoc definition
* @returns {string}
*/
function jsdocCommand( jsdoc ) {
var cmd = [];
cmd.unshift( jsdoc.options );
if ( jsdoc.tutorials.length > 0 ) {
cmd.push( "-u " + path.resolve( jsdoc.tutorials ) );
}
cmd.push( "-d " + path.resolve( jsdoc.dest ) );
cmd.push( "-t " + path.resolve( jsdoc.template ) );
cmd.push( "-c " + path.resolve( jsdoc.config ) );
_.each( jsdoc.src, function ( src ) {
cmd.push( path.resolve( src ) );
} );
cmd.unshift( path.resolve( "./node_modules/jsdoc/jsdoc" ) );
cmd.unshift( "node" );
return cmd.join( " " );
}
var tasks = {
shell : {
options : {
stdout : true,
stderr : true
},
/**
* TASK: Create the a documentation set for testing changes to the template
* @name shell:testdocs
* @memberOf module:Gruntfile
*/
testdocs : {
command : jsdocCommand( jsdocTestPages )
},
/**
* TASK: Create project documentation
* @name shell:dox
* @memberOf module:Gruntfile
*/
dox : {
command : jsdocCommand( projectDocs )
},
release1 : {
command : [
"touch Gruntfile.js",
"git add .",
'git commit -m "ready for release"',
].join( ";" )
},
release2 : {
command : ["npm version patch",
"git push",
"git push --tags",
"npm publish"
].join( "&&" )
}
},
jsdoc : {
testdocs : {
src : ['fixtures/**.js', "./README.md"],
jsdoc : "./node_modules/jsdoc/jsdoc.js",
options : {
destination : './testdocs',
rescurse : true,
"private" : true,
"template" : "./template",
"configure" : "./template/jsdoc.conf.json"
}
}
},
/**
* TASK: The less task creates the themed css file from main.less. The file is written to the template styles
* directory as site.[name of theme].css. Later the .conf file will look for the theme to apply based
* on this naming convention.
* @name less
* @memberOf module:Gruntfile
*/
less : {
dev : {
files : {
"template/static/styles/site.<%= jsdocConf.templates.theme %>.css" : "styles/main.less"
}
}
},
copy : {
docs : {
files : [
{expand : true, cwd : "dox/", src : ['**'], dest : '../docstrap-dox/'},
{expand : true, cwd : "themes/", src : ['**'], dest : '../docstrap-dox/themes'}
]
}
},
uglify : {
template : {
files : {
'template/static/scripts/docstrap.lib.js' : [
'bower_components/jquery/dist/jquery.min.js',
'bower_components/sunlight/src/sunlight.js',
'bower_components/sunlight/src/lang/sunlight.xml.js',
'bower_components/sunlight/src/**/*.js',
'bower_components/jquery.scrollTo/jquery.scrollTo.min.js',
'bower_components/jquery.localScroll/jquery.localScroll.min.js',
'bower_components/bootstrap/dist/js/bootstrap.min.js'
]
}
}
}
};
module.exports = function ( grunt ) {
tasks.jsdocConf = grunt.file.readJSON( 'template/jsdoc.conf.json' );
grunt.initConfig( tasks );
grunt.loadNpmTasks( 'grunt-contrib-less' );
grunt.loadNpmTasks( 'grunt-shell' );
grunt.loadNpmTasks( 'grunt-contrib-copy' );
grunt.loadNpmTasks( 'grunt-contrib-uglify' );
grunt.registerTask( "default", ["docs"] );
/**
* Builds the project's documentation
* @name docs
* @memberof module:Gruntfile
*/
grunt.registerTask( "docs", "Create the project documentation", ["shell:dox"] );
/**
* Compile the CSS and create the project documentation
* @name dev
* @memberof module:Gruntfile
*/
grunt.registerTask( "dev", "Compile the CSS and create the project documentation", ["less", "shell:dox"] );
/**
* TASK: Builds the main less file and then generates the test documents
* @name testdocs
* @memberof module:Gruntfile
*/
grunt.registerTask( "testdocs", "Builds the main less file and then generates the test documents", ["less:dev", "shell:testdocs"] );
/**
* TASK: Builds the whole shebang. Which means creating testdocs, the bootswatch fixtures and then resetting the
* styles directory.
* @name build
* @memberof module:Gruntfile
*/
grunt.registerTask( "build", "Builds the whole shebang. Which means creating testdocs, the bootswatch samples and then resetting the styles directory", ["uglify:template", "testdocs", "shell:dox", "bootswatch", "examples", "apply", "copy"] );
/**
* TASK: Applies the theme in the conf file and applies it to the styles directory.
* @name apply
* @memberof module:Gruntfile
*/
grunt.registerTask( "apply", "Applies the theme in the conf file and applies it to the styles directory", function () {
var def = {
less : "http://bootswatch.com/" + tasks.jsdocConf.templates.theme + "/bootswatch.less",
lessVariables : "http://bootswatch.com/" + tasks.jsdocConf.templates.theme + "/variables.less"
};
grunt.registerTask( "swatch-apply", _.partial( applyTheme, grunt, def ) );
grunt.task.run( ["swatch-apply"] );
} );
/**
* TASK: Grab all Bootswatch themes and create css from each one based on the main.less in the styles directory. NOTE that this will
* leave the last swatch downloaded in the styles directory, you will want to call "apply" afterwards
* @name bootswatch
* @memberof module:Gruntfile
*/
grunt.registerTask( "bootswatch", "Grab all Bootswatch themes and create css from each one based on the main.less in the styles directory", function () {
var toRun = [];
var done = this.async();
getBootSwatchList( function ( err, list ) {
if ( err ) {return done( err );}
_.each( list.themes, function ( entry ) {
toRun.push( "swatch" + entry.name );
grunt.registerTask( "swatch" + entry.name, _.partial( applyTheme, grunt, entry ) );
var key = "template/static/styles/site." + entry.name.toLowerCase() + ".css";
var def = {};
def[key] = "styles/main.less";
tasks.less["swatch" + entry.name] = {
files : def
};
toRun.push( "less:swatch" + entry.name );
} );
grunt.task.run( toRun );
done();
} );
} );
/**
* TASK:Create fixtures from the themes. The files must have been built first from the bootswatch task.
* @name examples
* @memberof module:Gruntfile
*/
grunt.registerTask( "examples", "Create samples from the themes", function () {
var toRun = [];
var done = this.async();
getBootSwatchList( function ( err, list ) {
if ( err ) {return done( err );}
_.each( list.themes, function ( entry ) {
var conf = grunt.file.readJSON( './fixtures/example.conf.json' );
conf.templates.theme = entry.name.toLowerCase();
grunt.file.write( "tmp/example.conf." + conf.templates.theme + ".json", JSON.stringify( conf, null, 4 ) );
var jsdenv = _.cloneDeep( jsdocExamplePages );
jsdenv.config = "./tmp/example.conf." + conf.templates.theme + ".json";
jsdenv.dest = "./themes/" + conf.templates.theme;
tasks.shell["example" + conf.templates.theme] = {
command : jsdocCommand( jsdenv )
};
toRun.push( "shell:example" + conf.templates.theme );
} );
grunt.registerTask( "cleanup", "", function () {
grunt.file["delete"]( "tmp/" );
} );
toRun.push( "cleanup" );
grunt.task.run( toRun );
done();
} );
} );
grunt.registerTask( "release", "Create the project documentation", ["shell:release1", "shell:release2"] );
};
/**
* Applies one of the Bootswatch themes to the working `styles` directory. When you want to modify a particular theme, this where you
* get the basis for it. The files are written to `./styles/variables.less` and `./styles/bootswatch.less`. The `./styles/main.less`
* file includes them directly, so after you apply the theme, modify `main.less` to your heart's content and then run the `less` task
* as in
*
* grunt less
*
* @param {object} grunt The grunt object reference
* @param {object} definition The swatch definition files
* @param {string} definition.less The url to the `bootswatch.less` file
* @param {string} definition.lessVariables The url to the `variables.less` file
* @private
*/
function applyTheme( grunt, definition ) {
//noinspection JSHint
var webProtocol = tasks.jsdocConf.templates.protocol || "//";
var done = this.async();
async.waterfall( [
function ( cb ) {
getBootSwatchComponent( definition.less, function ( err, swatch ) {
if ( err ) {return cb( err );}
var fullPath = path.join( __dirname, "styles/bootswatch.less" );
fs.writeFile( fullPath, swatch.replace( "http://", webProtocol ), cb );
} );
},
function ( cb ) {
getBootSwatchComponent( definition.lessVariables, function ( err, swatch ) {
if ( err ) {return cb( err );}
var fullPath = path.join( __dirname, "styles/variables.less" );
fs.writeFile( fullPath, swatch.replace( "http://", webProtocol ), cb );
} );
}
], done );
}
/**
* Gets the list of available Bootswatches from, well, Bootswatch.
*
* @see http://news.bootswatch.com/post/22193315172/bootswatch-api
* @param {function(err, responseBody)} done The callback when complete
* @param {?object} done.err If an error occurred, you will find it here.
* @param {object} done.responseBody This is a parsed edition of the bootswatch server's response. It's format it defined
* by the return message from [here](http://api.bootswatch.com/)
* @private
*/
function getBootSwatchList( done ) {
request('http://api.bootswatch.com/3/', function(error, response, body) {
if (error) {
return done(error);
}
done(null, JSON.parse(body));
});
}
/**
* This method will get one of the components from Bootswatch, which is generally a `less` file or a `lessVariables` file.
*
* @see http://news.bootswatch.com/post/22193315172/bootswatch-api
* @param {string} url The url to retreive from
* @param {function(err, responseText)} done The callback when complete
* @param {?object} done.err If an error occurred, you will find it here.
* @param {string} done.responseText The body of whatever was returned
* @private
*/
function getBootSwatchComponent( url, done ) {
var body = "";
var req = request(url, function ( error, response, body ) {
if (error) {
return done(error);
}
done(null, body);
});
}