Merge branch 'master' into new-functionality

Author: justinbmeyer

.gitignore

@@ -1,7 +1,10 @@
+package-lock.json
 node_modules
 site/static/
 site/static/build/
 site/static/dist/
 site/templates/
 test/tmp
-.idea/
+.idea/
+.vscode
+.DS_Store

bit-docs.js

@@ -3,8 +3,11 @@ var _ = require("lodash");
 var tags = require("./tags/tags");
 
 var mergeOnto = function(prop, dest, source){
+    if(!dest[prop]) {
+        dest[prop] = [];
+    }
     if(source[prop]) {
-        dest[prop] = dest[prop].concat(source[prop])
+        dest[prop] = dest[prop].concat(source[prop]);
     }
 };
 
@@ -14,13 +17,31 @@ var mergeOnto = function(prop, dest, source){
  * @group bit-docs-generate-html/modules modules
  * @group bit-docs-generate-html/static static
  * @group bit-docs-generate-html/templates templates
+ * @group bit-docs-generate-html/generated generated
  * @group bit-docs-generate-html/types types
  *
- * @description Generates HTML for a docMap.  Supports plugins.
+ * @description Generates HTML for a docMap and handles the `html` hook.
  *
  * @body
  *
- * TBD
+ * This plugin registers onto these hooks:
+ *   - `tags`
+ *   - `generator`
+ * 
+ * Registering the `tags` hook adds the `@templaterender` tag.
+ * 
+ * Registering the `generator` hook makes it so this plugin can generate the
+ * HTML output from the provided [bit-docs/types/docMap]. The entry point for
+ * this generator is [bit-docs-generate-html/html].
+ * 
+ * This plugin handles the `html` hook, which allows other plugins to hook into
+ * the generation process, to do things like include their own static assets,
+ * or provide their own mustache templates.
+ * 
+ * This plugin provides a default set of mustache templates and static assets.
+ * These mustache templates and less styles can be copied over into a theme
+ * plugin and customized. Any custom mustache template will override a default
+ * of the same name.
  */
 module.exports = function(bitDocs){
     bitDocs.register("generator", generator);
@@ -32,12 +53,13 @@ module.exports = function(bitDocs){
             siteConfig.html = {
                 dependencies: {},
                 static: [],
-                templates: []
+                templates: [],
+                staticDist: []
             };
         }
         var html = siteConfig.html;
         _.assign(html.dependencies, htmlConfig.dependencies || {});
-
+        mergeOnto("staticDist", html, htmlConfig);
         mergeOnto("static", html, htmlConfig);
         mergeOnto("templates", html, htmlConfig);
     });

build/build.js

@@ -1,21 +1,20 @@
 /**
- * @property {{}} documentjs.generators.html.build
- * @parent documentjs.generators.html.properties
+ * @parent bit-docs-generate-html/modules
+ * @module {{}} bit-docs-generate-html/build/build
  * 
- * @group documentjs.generators.html.build.methods 0 methods
- * @group documentjs.generators.html.build.types 1 types
- * 
- * A collection of helpers used to build and compile the templates
- * used to render each [documentjs.process.docObject docObject] into
- * HTML and build the static JS and CSS used by that HTML.
+ * A collection of helpers used to build and compile the templates used to
+ * render each [bit-docs/types/docObject] into HTML and build the static JS and
+ * CSS used by that HTML.
  * 
  * @body
  * 
+ * Requires and exports these other modules:
+ * - [bit-docs-generate-html/build/renderer] as `renderer`.
+ * - [bit-docs-generate-html/build/static_dist] as `staticDist`.
+ * - [bit-docs-generate-html/build/templates] as `templates`.
+ * - [bit-docs-generate-html/build/helpers] as `helpers`.
  */
-
-
-
 exports.renderer = require("./renderer");
 exports.staticDist = require("./static_dist");
 exports.templates = require("./templates");
-exports.helpers = require("./helpers");
+exports.helpers = require("./helpers");

build/build_hash.js

@@ -1,29 +1,32 @@
 var md5 = require('md5');
 
 /**
- * @function documentjs.generators.html.build.buildHash
- * @parent documentjs.generators.html.build.methods
+ * @parent bit-docs-generate-html/modules
+ * @module {function} bit-docs-generate-html/build/build_hash
  * 
  * Returns a unique hash for the options that control the build.
  * 
- * @signature `.build.buildHash(options)`
+ * @signature `buildHash(options)`
  * 
  * @param {{}} options Options that might change the characteristic of the build:
  * 
- * @option {Boolean} [minifyBuild=true] If set to `false` the build will not 
- * be minified. This behavior should be implemented by the "build" module.
+ *   @option {Boolean} [minifyBuild=true] If set to `false` the build will not be
+ *   minified. This behavior should be implemented by the "build" module.
+ *   
+ *   @option {Boolean} [devBuild=false] If set to `true` the build will not be
+ *   built and copied in "development" mode.
+ *   
+ *   @option {String} static The location of static content used to overwrite or
+ *   add to the default static content.
+ *   
+ *   @option {String} [templates] The location of templates used to overwrite or
+ *   add to the default templates.
  * 
- * @option {Boolean} [devBuild=false] If set to `true` the build will not be built
- * and copied in "development" mode.
- * 
- * @option {String} static The location of static content used to overwrite or
- * add to the default static content.
- * 
- * @option {String} [templates] The location of templates used to overwrite or
- * add to the default templates.
+ * @return {String} a hash that represents this build.
  * 
+ * @body
  * 
- * @return {String} a hash that represents this build.
+ * The generated hash will be something like `917c51373c902dc4a003c7fd949774c5`.
  */
 module.exports = function(options){
 	var values = {};

build/build_test.js

@@ -1,41 +1,40 @@
+var fs = require('fs');
+var path = require('path');
+var assert = require('assert');
+var Q = require('q');
+var rimraf = require('rimraf');
+var getRenderer = require('./get_renderer');
+var getPartials = require('./get_partials');
+var build = require("./build");
 
+var rmdir = Q.denodeify(rimraf);
+var read = Q.denodeify(fs.readFile);
 
-var getRenderer = require('./get_renderer'),
-	getPartials = require('./get_partials'),
-	build = require("./build"),
-	assert = require('assert'),
-	Q = require('q'),
-	path = require('path'),
-	rmdir = require('rimraf'),
-	fs = require('fs');
+require("./make_default_helpers_test");
 
-describe("documentjs/lib/generators/html/build",function(){
+describe("documentjs/lib/generators/html/build", function(){
 
-	beforeEach(function(done){
-		rmdir(path.join(__dirname,"..","site","static"), function(e){
-			rmdir(path.join(__dirname,"..","site","templates"), done);
+	beforeEach(function(){
+		return rmdir(path.join(__dirname, "..", "site", "static")).then(function(){
+			return rmdir(path.join(__dirname, "..", "site", "templates"));
 		});
 	});
 
-	it("get_renderer and get_partial work",function(done){
-		Q.all([
+	it("get_renderer and get_partial work", function(){
+		return Q.all([
 			getRenderer('build/test/templates'),
 			getPartials('build/test/templates')
 		]).then(function(results){
-
 			var renderer = results[0];
-
 			var result = renderer({subject: "World"});
 
 			assert.equal(result, "<html><h1>Hello World</h1></html>");
-			done();
-		},done).catch(done);
+		});
 	});
 
-	it("build.renderer build.templates build.helpers",function(done){
-
+	it("build.renderer build.templates build.helpers", function(){
 		var options = {
-			html: { templates: path.join(__dirname,"test","templates_with_helpers") },
+			html: { templates: path.join(__dirname, "test", "templates_with_helpers") },
 			dest: "XXXXYYYZZZ",
 			forceBuild: true,
 			pageConfig: {
@@ -52,13 +51,11 @@ describe("documentjs/lib/generators/html/build",function(){
 		};
 
 
-		Q.all([
+		return Q.all([
 			build.renderer(buildTemplatesPromise, options),
 			build.helpers(buildTemplatesPromise, {}, options, getCurrent)
 		]).then(function(results){
-
 			var renderer = results[0];
-
 			var result = renderer({
 				subject: "World",
 				src: "./index.js",
@@ -67,14 +64,13 @@ describe("documentjs/lib/generators/html/build",function(){
 			});
 
 			assert.equal(result, "<html><h1>HELLO World</h1>\n</html>");
-			done();
-		},done).catch(done);
+		});
 
 	});
 
-	it("Does ignoreTemplateRender",function(done){
+	it("Does ignoreTemplateRender", function(){
 		var options = {
-			html: {templates: path.join(__dirname,"test","render_body_option")},
+			html: {templates: path.join(__dirname, "test", "render_body_option")},
 			dest: "XXXXYYYZZZ",
 			forceBuild: true,
 			pageConfig: {
@@ -90,41 +86,71 @@ describe("documentjs/lib/generators/html/build",function(){
 			return data;
 		};
 
-		Q.all([
+		return Q.all([
 			build.renderer(buildTemplatesPromise, options),
 			build.helpers(buildTemplatesPromise, {}, options, getCurrent)
 		]).then(function(results){
-
 			var renderer = results[0];
-
 			var result = renderer({body: "{{message}} stuff"});
 
 			assert.equal(result, "<html><h1>{{message}} stuff</h1>\n<p>static</p></html>");
-			done();
-		},done).catch(done);
+		});
 
 	});
 
-	it("builds the static dist", function(done){
+	it("builds the static dist", function(){
 		this.timeout(120000);
-		build.staticDist({
+		return build.staticDist({
 			forceBuild: true,
-			html: {dependencies: {"can-component": "3.0.0-pre.9"}}
-		}).then(function(result){
-			fs.readFile(path.join(__dirname, "..", result.distFolder, "bundles","bit-docs-site","static.js"), function(err, res){
-				if(err) {
-					done(err);
-				} else {
-					assert.ok(/can-component/.test(res), "got static.js with component");
-					done();
+			html: {
+				dependencies: {
+					"can-component": "3.0.0-pre.9"
 				}
-			});
-		}, done);
+			}
+		}).then(function(result){
+			return read(path.join(__dirname, "..", result.distFolder, "bundles", "bit-docs-site", "static.js"));
+		}).then(function(res){
+			assert.ok(/can-component/.test(res), "got static.js with component");
+		});
 	});
 
-	it("makes linked content",function(done){
+	it("copy absolute staticDist folders to static dist", function(){
+		this.timeout(120000);
+		return build.staticDist({
+			forceBuild: true,
+			html: {
+				staticDist: [
+					path.join(__dirname, '..', 'test-static-dist')
+				]
+			},
+		}).then(function(result){
+			return read(path.join(__dirname, "..", result.distFolder, "test.css"));
+		}).then(function(res){
+			assert.ok(/#TestID/.test(res), "got test.css file");
+		});
+	});
+
+	it("copy relative staticDist folders to static dist", function(){
+		this.timeout(120000);
+		return build.staticDist({
+			forceBuild: true,
+			html: {
+				staticDist: [
+					'./test-static-dist'
+				]
+			},
+		}).then(function(result){
+			return read(path.join(__dirname, "..", result.distFolder, "test.css"));
+		}).then(function(res){
+			assert.ok(/#TestID/.test(res), "got test.css file");
+		});
+	});
+
+	it("makes linked content", function(){
 		var options = {
-			html: { templates: path.join(__dirname,"test","escaped") },
+			html: {
+				templates: path.join(__dirname, "test", "escaped")
+			},
 			dest: "XXXXYYYZZZ",
 			forceBuild: true,
 			pageConfig: {
@@ -149,18 +175,14 @@ describe("documentjs/lib/generators/html/build",function(){
 			something: {name: "something", title: "<something/>"}
 		};
 
-
-		Q.all([
+		return Q.all([
 			build.renderer(buildTemplatesPromise, options),
 			build.helpers(buildTemplatesPromise, docMap, options, getCurrent)
 		]).then(function(results){
-
 			var renderer = results[0];
-
 			var result = renderer(docObject);
+
 			assert.equal(result, "<html><p>This is <a href=\"something.html\" title=\"something\"><something/></a></p>\n\n</html>");
-			done();
-		},done).catch(done);
+		});
 	});
-
 });