From 39faae355ba61db0bd293984f9f5ba08a19a5b90 Mon Sep 17 00:00:00 2001 From: Kevin Druff Date: Mon, 20 Apr 2015 20:09:46 -0400 Subject: [PATCH 1/7] This should be a good commit --- README.md | 53 ++++---- index.js | 349 ++++++++++++++++++++++++++++++++++----------------- package.json | 2 +- 3 files changed, 258 insertions(+), 146 deletions(-) diff --git a/README.md b/README.md index cb44fa0..4097deb 100644 --- a/README.md +++ b/README.md @@ -1,57 +1,56 @@ # gulp-kss -Gulp plugin for KSS ([Knyle Stype Sheets](http://warpspire.com/kss/)) documentation generation. +Gulp plugin for KSS ([Knyle Style Sheets](http://warpspire.com/kss/)) documentation generation. -This plugin is based on [kss-node](https://github.com/hughsk/kss-node) and generates a styleguide based on code documentation. The plugin is mainly a fork of `kss-nodes`'s bin script, not how a beautiful gulp plugin should look like, but it works. - -This plugin currently lacks tests. +This plugin is based on [kss-node](https://github.com/hughsk/kss-node) and generates a styleguide based on code documentation. It builds upon the original [gulp-kss](https://github.com/philj/gulp-kss) by PhilJ but integrates newer node-kss features including custom properties, handlebars helpers, and more. ## Install ``` -npm install gulp-kss +git clone https://github.com/kedruff/gulp-kss.git +npm install ``` ## Usage Pipe all source files you want to document through `gulp-kss`, also the ones which are usually imported. -In addition to that you need to create a concated and compiled version of your styles at `public/style.css`. - ```javascript -var gulp = require('gulp'); -var gulpless = require('gulp-less'); -var gulpkss = require('gulp-kss'); -var gulpconcat = require('gulp-concat'); - -gulp.src(['styles/**/*.less']) - .pipe(gulpkss({ - overview: __dirname + '/styles/styleguide.md' - })) +gulp.src( ['array/*.scss', 'ofSource/*.scss', 'sass/files/*.scss'] ) + .pipe( gulpkss({ + template: './node_modules/kss/lib/template', + kss: { + multiline: true, + typos: false + }, + custom: [], + helpers: '', + css: [], + js: [] + }) ) .pipe(gulp.dest('styleguide/')); -// Concat and compile all your styles for correct rendering of the styleguide. -gulp.src('styles/main.less') - .pipe(gulpless()) - .pipe(gulpconcat('public/style.css')) - .pipe(gulp.dest('styleguide/')); ``` - ## Options -* `overview`: Absolute path to markdown file which is used for styleguide home page -* `templateDirectory`: Absolute path to template directory, by default `kss-node` default template is used. -* `kss`: Options supported by [`kss-node`](https://github.com/hughsk/kss-node/wiki/Module-API#wiki-options) +* **template**: A path relative to your `gulpfile.js` containing a custom template (Default: `./node_modules/kss/lib/template/`) +* **destination**: A path relative to your `gulpfile.js` where you would your compiled guide to live (Default: `./docs/styleguide/`) +* **kss**: kss options + * **multiline** : As far as the parser is concerned, all but the last two paragraphs (separated by two line breaks) in a block are considered to be part of the description. In the case you don't have any modifiers but a large description it'll try to pick up this scenario. This setting's enabled by default, but you can disable it by adding multiline: false to your options. + * **typos**: Thanks to [natural](https://github.com/NaturalNode/natural), `kss-node` can parse keywords phonetically rather then by their string value. In short: make a typo and the library will do its best to read it anyway. Enable this by setting typos to true in the options object. +* **custom**: A custom property name when parsing KSS comments +* **helpers**: Specify the location of custom [handlebars helpers](http://bit.ly/kss-helpers) (Default: `./lib/template/helpers`) +* **css**: Specify the URL of a CSS file to include in the style guide +* **js**: Specify the URL of a JavaScript file to include in the style guide ## LICENSE (MIT License) -Copyright (c) 2014 DigitalWerft philipp@digitalwerft.com +Copyright (c) 2015 Capital One Financial (Kevin Druff) Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - diff --git a/index.js b/index.js index e647ef5..fe527be 100644 --- a/index.js +++ b/index.js @@ -1,158 +1,199 @@ -var path = require('path'); -var fs = require('fs'); - -var through = require('through'); -var gulp = require('gulp'); -var gutil = require('gulp-util'); -var gulpless = require('gulp-less'); -var kss = require('kss'); -var marked = require('marked'); -var handlebars = require('handlebars'); -var PluginError = gutil.PluginError; -var File = gutil.File; - -var handlebarHelpers = require('./handlebarHelpers'); - -/* - This script is based and recycles a lot of code of the bin script of kss-node - https://github.com/hughsk/kss-node/blob/master/bin/kss-node - */ +var fs = require('fs'), + gulp = require('gulp'), + kss = require('kss'), + path = require('path'), + gutil = require('gulp-util'), + util = require('util'), + assign = require('object-assign'), + handlebars = require('handlebars'), + gulpless = require('gulp-less'), + sass = require('gulp-sass'), + File = require('vinyl'), + through = require('through'), + custom = [], + styleguide, + handlebarHelpers = require('./handlebarHelpers'); module.exports = function(opt) { 'use strict'; - if (!opt) opt = {}; - if (!opt.templateDirectory) opt.templateDirectory = __dirname + '/node_modules/kss/lib/template'; - if (!opt.kssOpts) opt.kssOpts = {}; - - var buffer = []; - var firstFile = null; + var styleguide, + firstFile = null, + buffer = [], + defaults = { + template: './node_modules/kss/lib/template', + kss: { + mask: {}, + markdown: true, + multiline: true, + typos: false + }, + custom: [], + helpers: '', + css: [], + js: [] + }, + cache = { + partial: {} + }; + + opt = assign(defaults, opt); /* Is called for each file and writes all files to buffer */ - function bufferContents(file){ + + function bufferContents(file) { if (file.isNull()) return; // ignore - if (file.isStream()) return this.emit('error', new PluginError('gulp-kss', 'Streaming not supported')); + if (file.isStream()) return this.emit('error', new PluginError('gulp-kss', 'Streaming not supported')); if (!firstFile) firstFile = file; - buffer.push(file.contents.toString('utf8')); } - /* Is called when all files were added to buffer */ - function endStream(){ - var template = fs.readFileSync(path.join(opt.templateDirectory, 'index.html'), 'utf8'); + function processKss() { + var templatePath = path.resolve(process.cwd() + '/' + opt.template), + template = fs.readFileSync(templatePath + '/index.html', 'utf8'), + self = this; + template = handlebars.compile(template); - var self = this; + kss.parse(buffer, opt.kss, function(err, guide) { + if (err) { + console.log('Error', error); + throw err; + } - kss.parse(buffer, opt.kssOpts, function (err, styleguide) { - if (err) console.log('Error', error); + styleguide = guide; + // Compile the Handlebars template - var sections = styleguide.section('*.'), - i, sectionCount = sections.length, - sectionRoots = [], currentRoot, - rootCount, childSections = []; + var i, + rootCount, + currentRoot, + sections = styleguide.section(), + sectionCount = sections.length, + sectionRoots = [], + childSections = [], + partial, + files = []; - // Accumulate all of the sections' first indexes - // in case they don't have a root element. + // Throw an error if no KSS sections are found in the source files. + if (sectionCount === 0) { + throw 'No KSS documentation discovered in source files.'; + } for (i = 0; i < sectionCount; i += 1) { - currentRoot = sections[i].reference().match(/[0-9]*\.?/)[0].replace('.', ''); + // Register all the markup blocks as Handlebars partials. + if (sections[i].markup()) { + partial = { + name: sections[i].reference(), + reference: sections[i].reference(), + file: '', + markup: sections[i].markup(), + data: {} + }; + // If the markup is a file path, attempt to load the file. + if (partial.markup.match(/^[^\n]+\.(html|hbs)$/)) { + partial.file = partial.markup; + partial.name = path.basename(partial.file, path.extname(partial.file)); + files = []; + for (var key in argv.source) { + if (!files.length) { + files = glob.sync(argv.source[key] + '/**/' + partial.file); + } + } + // If the markup file is not found, note that in the style guide. + if (!files.length) { + partial.markup += ' NOT FOUND!'; + } + console.log(' - ' + partial.reference + ': ' + partial.markup); + if (files.length) { + // Load the partial's markup from file. + partial.file = files[0]; + partial.markup = fs.readFileSync(partial.file, 'utf8'); + // Load sample data for the partial from the sample .json file. + if (fs.existsSync(path.dirname(partial.file) + '/' + partial.name + '.json')) { + try { + partial.data = require(path.dirname(partial.file) + '/' + partial.name + '.json'); + } catch (e) { + partial.data = {}; + } + } + } + } else { + console.log(' - ' + partial.reference + ': inline markup'); + } + + // Register the partial using the filename (without extension) or using + // the style guide reference. + handlebars.registerPartial(partial.name, partial.markup); + + // Save the name of the partial and its data for retrieval in the markup + // helper, where we only know the reference. + cache.partial[partial.reference] = { + name: partial.name, + data: partial.data + }; - if (!~sectionRoots.indexOf(currentRoot)) { - sectionRoots.push(currentRoot); } - } - sectionRoots.sort(); - rootCount = sectionRoots.length; + // Accumulate all of the sections' first indexes + // in case they don't have a root element. + currentRoot = sections[i].reference().split(/(?:\.|\s+\-\s+)/)[0]; + if (sectionRoots.indexOf(currentRoot) === -1) { + sectionRoots.push(currentRoot); + } - handlebarHelpers(handlebars, styleguide); + console.log('...Generating style guide sections:'); + } // Now, group all of the sections by their root // reference, and make a page for each. - for (i = 0; i < rootCount; i += 1) { - childSections = styleguide.section(sectionRoots[i]+'.*'); - - var content = template({ - styleguide: styleguide, - sections: jsonSections(childSections), - rootNumber: sectionRoots[i], - sectionRoots: sectionRoots, - overview: false, - argv: {} - }); - - var joinedPath = path.join(firstFile.base, 'section-' + sectionRoots[i] + '.html'); - - var file = new File({ - cwd: firstFile.cwd, - base: firstFile.base, - path: joinedPath, - contents: new Buffer(content) + rootCount = sectionRoots.length; + handlebarHelpers(handlebars, styleguide, cache); + if (fs.existsSync(opt.helpers)) { + var helperFiles = fs.readdirSync(opt.helpers); + helperFiles.forEach(function(fileName) { + if (path.extname(fileName) !== '.js') { + return; + } + opt.helpers = path.normalize(opt.helpers); + opt.helpers = path.resolve(process.cwd(), opt.helpers); + + var helper = require(opt.helpers + '/' + fileName); + if (typeof helper.register === 'function') { + helper.register(handlebars); + } }); - - self.emit('data', file); } - // Generate Overview File - if (opt.overview) { - gulp.src(opt.overview) - .pipe(through(function (file) { - - var content = template({ - styleguide: styleguide, - sectionRoots: sectionRoots, - sections: jsonSections(childSections), - rootNumber: 0, - argv: {}, - overview: marked(file.contents.toString('utf8'), 'utf8') - }); - - var joinedPath = path.join(firstFile.base, 'index.html'); - - var file = new File({ - cwd: firstFile.cwd, - base: firstFile.base, - path: joinedPath, - contents: new Buffer(content) - }); - - self.emit('data', file); - })); + for (i = 0; i < rootCount; i += 1) { + childSections = styleguide.section(sectionRoots[i] + '.*'); + self.emit('data', generatePage(styleguide, childSections, sectionRoots[i], sectionRoots, template)); } - // Copy template assets, less compilation added because default template uses it - gulp.src(path.join(opt.templateDirectory, '/**/*.less')) + + // Generate the homepage. + childSections = []; + self.emit('data', generatePage(styleguide, childSections, 'styleguide.homepage', sectionRoots, template)); + + gulp.src(templatePath + '/**/*.{sass, scss, less}') .pipe(gulpless()) - .pipe(through(function (file) { + .pipe(sass()) + .pipe(through(function(file) { - self.emit('data', file); + self.emit('data', file); }).on('end', function() { - emitEnd(self); + emitEnd(self); })); - gulp.src(path.join(opt.templateDirectory, '/**/*.js')) - .pipe(through(function (file) { + gulp.src(path.join(templatePath, '/**/*.js')) + .pipe(through(function(file) { - self.emit('data', file); + self.emit('data', file); }).on('end', function() { - emitEnd(self); + emitEnd(self); })); + }); } - // duplicate of underscore's _.after() function http://underscorejs.org/docs/underscore.html#section-76 - var underscoreAfter = function underscoreAfter(times, func) { - return function() { - if (--times < 1) { - return func.apply(this, arguments); - } - }; - }; - - var emitEnd = underscoreAfter(2, function emitEnd(self) { - self.emit('end'); - }); - function jsonSections(sections) { return sections.map(function(section) { return { @@ -167,8 +208,7 @@ module.exports = function(opt) { }); } - // Convert an array of `KssModifier` instances to a JSON object. - function jsonModifiers (modifiers) { + function jsonModifiers(modifiers) { return modifiers.map(function(modifier) { return { name: modifier.name(), @@ -178,5 +218,78 @@ module.exports = function(opt) { }); } - return through(bufferContents, endStream); + function generatePage(styleguide, sections, root, sectionRoots, template) { + var files, + filename = '', + homepageText = false, + styles = opt.css, + scripts = opt.js; + + var args = { + styleguide: styleguide + } + // Create the HTML to load the optional CSS and JS. + for (var key in opt.css) { + styles = styles + '\n'; + } + for (var key in opt.js) { + scripts = scripts + '\n'; + } + + + if (root == 'styleguide.homepage') { + filename = 'index.html'; + console.log(' - homepage'); + // Ensure homepageText is a non-false value. + if (fs.existsSync(opt.template + '/styleguide.md')) { + homepageText = ' ' + marked(fs.readFileSync(opt.template + '/styleguide.md', 'utf8')); + } + if (!homepageText) { + homepageText = ' '; + console.log(' ...no homepage content found in styleguide.md.'); + } + } else { + filename = 'section-' + kss.KssSection.prototype.encodeReferenceURI(root) + '.html'; + console.log( + ' - section ' + root + ' [', + styleguide.section(root) ? styleguide.section(root).header() : 'Unnamed', + ']' + ); + } + var content = template({ + styleguide: styleguide, + sections: sections.map(function(section) { + return section.JSON(opt.custom); + }), + sectionRoots: sectionRoots, + rootName: root, + homepage: homepageText, + overview: false, + styles: styles, + scripts: scripts + }), + filename = path.join(firstFile.base, filename), + file = new File({ + cwd: firstFile.cwd, + base: firstFile.base, + path: filename, + contents: new Buffer(content) + }); + + return file; + }; + + var underscoreAfter = function underscoreAfter(times, func) { + return function() { + if (--times < 1) { + return func.apply(this, arguments); + } + }; + }; + + var emitEnd = underscoreAfter(2, function emitEnd(self) { + self.emit('end'); + }); + + return through(bufferContents, processKss); }; \ No newline at end of file diff --git a/package.json b/package.json index 7208817..6a55e90 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "gulp-kss", - "version": "0.0.1", + "version": "0.2.0", "description": "Gulp plugin for KSS (Knyle Style Sheets) documentation generation", "repository": { "type": "git", From 398b816ead782f76126497f9a1efe99450ec601a Mon Sep 17 00:00:00 2001 From: Kevin Druff Date: Tue, 21 Apr 2015 09:34:52 -0400 Subject: [PATCH 2/7] updating handleBars helpers --- handlebarHelpers.js | 217 ++++++++++++++++++++++++++++---------------- index.js | 91 ++++++++++--------- package.json | 2 + 3 files changed, 185 insertions(+), 125 deletions(-) diff --git a/handlebarHelpers.js b/handlebarHelpers.js index 0a83ca6..39bb0d0 100644 --- a/handlebarHelpers.js +++ b/handlebarHelpers.js @@ -1,33 +1,10 @@ var kss = require('kss') -module.exports = function (handlebars, styleguide) { - /** - * Equivalent to the {#if} block helper with multiple arguments. - */ - handlebars.registerHelper('ifAny', function() { - var argLength = arguments.length - 2, - content = arguments[argLength + 1], - success = true; - - for (var i = 0; i < argLength; i += 1) { - if (!arguments[i]) { - success = false; - break; - } - } - - return success ? content.fn(this) : content.inverse(this); - }); - - /** - * Returns a single section, found by its reference number - * @param {String|Number} reference The reference number to search for. - */ - handlebars.registerHelper('section', function(reference) { +module.exports = function (handlebars, styleguide, cache) { + handlebars.registerHelper('section', function(reference, options) { var section = styleguide.section(reference); - if (!section) return false; - return arguments[arguments.length-1](section.data); + return section ? options.fn(section.data) : false; }); /** @@ -35,21 +12,20 @@ module.exports = function (handlebars, styleguide) { * a query for all children and descendants of that reference. * @param {Mixed} query The section query */ - handlebars.registerHelper('eachSection', function(query) { - var sections, - i, l, buffer = ""; - query = (typeof query === 'string') ? query : query.toString(); + handlebars.registerHelper('eachSection', function(query, options) { + var buffer = '', + sections, + i, l; - if (!query.match(/x|\*/g)) { - query = new RegExp('^' + query + '$|^' + query + "\\..*"); + if (!query.match(/\bx\b|\*/g)) { + query = query + '.*'; } sections = styleguide.section(query); - if (!sections) return ''; l = sections.length; for (i = 0; i < l; i += 1) { - buffer += arguments[arguments.length-1].fn(sections[i].data); + buffer += options.fn(sections[i].data); } return buffer; @@ -58,93 +34,174 @@ module.exports = function (handlebars, styleguide) { /** * Loop over each section root, i.e. each section only one level deep. */ - handlebars.registerHelper('eachRoot', function() { - var sections, - i, l, buffer = ""; + handlebars.registerHelper('eachRoot', function(options) { + var buffer = '', + sections, + i, l; sections = styleguide.section('x'); if (!sections) return ''; l = sections.length; for (i = 0; i < l; i += 1) { - buffer += arguments[arguments.length-1].fn(sections[i].data); + buffer += options.fn(sections[i].data); } return buffer; }); + /** + * Equivalent to "if the given reference is numeric". e.g: + * + * {{#ifNumeric reference}} + * REFERENCES LIKE 4.0 OR 4.1.14 + * {{else}} + * ANYTHING ELSE + * {{/ifNumeric}} + */ + handlebars.registerHelper('ifNumeric', function(reference, options) { + return (typeof reference == 'number' || typeof reference == 'string' && reference.match(/^[\.\d]+$/)) ? options.fn(this) : options.inverse(this); + }); + + /** + * Equivalent to "if the current reference is X". e.g: + * + * {{#ifReference 'base.headings'}} + * IF CURRENT REFERENCE IS base.headings ONLY + * {{else}} + * ANYTHING ELSE + * {{/ifReference}} + */ + handlebars.registerHelper('ifReference', function(reference, options) { + return (this.reference && reference == this.reference) ? options.fn(this) : options.inverse(this); + }); + + /** + * Equivalent to "unless the current reference is X". e.g: + * + * {{#unlessReference 'base.headings'}} + * ANYTHING ELSE + * {{else}} + * IF CURRENT REFERENCE IS base.headings ONLY + * {{/unlessReference}} + */ + handlebars.registerHelper('unlessReference', function(reference, options) { + return (!this.reference || reference != this.reference) ? options.fn(this) : options.inverse(this); + }); + /** * Equivalent to "if the current section is X levels deep". e.g: * - * {{#refDepth 1}} + * {{#ifDepth 1}} * ROOT ELEMENTS ONLY * {{else}} * ANYTHING ELSE - * {{/refDepth}} + * {{/ifDepth}} */ - handlebars.registerHelper('whenDepth', function(depth, context) { - if (!(context && this.refDepth)) { - return ''; - } - if (depth == this.refDepth) { - return context.fn(this); - } - if (context.inverse) { - return context.inverse(this); - } + handlebars.registerHelper('ifDepth', function(depth, options) { + return (this.depth && depth == this.depth) ? options.fn(this) : options.inverse(this); + }); + + /** + * Equivalent to "unless the current section is X levels deep". e.g: + * + * {{#unlessDepth 1}} + * ANYTHING ELSE + * {{else}} + * ROOT ELEMENTS ONLY + * {{/unlessDepth}} + */ + handlebars.registerHelper('unlessDepth', function(depth, options) { + return (!this.depth || depth != this.depth) ? options.fn(this) : options.inverse(this); }); /** * Similar to the {#eachSection} helper, however will loop over each modifier - * @param {Object} section Supply a section object to loop over it's modifiers. Defaults to the current section. + * @param {Object} section Supply a section object to loop over its modifiers. Defaults to the current section. */ - handlebars.registerHelper('eachModifier', function(section) { - var modifiers, i, l, buffer = ''; + handlebars.registerHelper('eachModifier', function() { + var modifiers, + options = arguments[arguments.length - 1], + buffer = '', + i, l; - // Default to current modifiers, but allow supplying a custom section - if (section.data) modifiers = section.data.modifiers; - modifiers = modifiers || this.modifiers || false; + // Default to current modifiers, but allow supplying a custom section. + modifiers = (arguments.length > 1 && arguments[0].data) ? arguments[0].data.modifiers : this.modifiers; - if (!modifiers) return {}; + if (!modifiers) return ''; l = modifiers.length; for (i = 0; i < l; i++) { - buffer += arguments[arguments.length-1].fn(modifiers[i].data || ''); + buffer += options.fn(modifiers[i].data || ''); } return buffer; }); /** - * Outputs a modifier's markup, if possible. - * @param {Object} modifier Specify a particular modifier object. Defaults to the current modifier. + * Similar to the {#eachSection} helper, however will loop over each parameter + * @param {Object} section Supply a section object to loop over its parameters. Defaults to the current section. */ - handlebars.registerHelper('modifierMarkup', function(modifier) { - modifier = arguments.length < 2 ? this : modifier || this || false; + handlebars.registerHelper('eachParameter', function() { + var parameters, + options = arguments[arguments.length - 1], + buffer = '', + i, l; - if (!modifier) { - return false; - } + // Default to current parameters, but allow supplying a custom section. + parameters = (arguments.length > 1 && arguments[0].data) ? arguments[0].data.parameters : this.parameters; - // Maybe it's actually a section? - if (modifier.modifiers) { - return new handlebars.SafeString( - modifier.markup - ); - } + if (!parameters) return ''; - // Otherwise return the modifier markup - return new handlebars.SafeString( - new kss.KssModifier(modifier).markup() - ); + l = parameters.length; + for (i = 0; i < l; i++) { + buffer += options.fn(parameters[i].data || ''); + } + return buffer; }); /** - * Quickly avoid escaping strings - * @param {String} arg The unescaped HTML + * Outputs the current section's or modifier's markup. */ - handlebars.registerHelper('html', function(arg) { - return new handlebars.SafeString(arg || ''); - }); + handlebars.registerHelper('markup', function() { + var section, + modifier = false, + template, + partial, + data; + + if (!this) { + return ''; + } + + // Determine if the element is a section object or a modifier object. + if (this.modifiers) { + // If this is the section object, use the default markup without a modifier class. + section = new kss.KssSection(this); + } + else { + // If this is the markup object, find the modifier class and the section object. + modifier = new kss.KssModifier(this); + section = modifier.section(); + } + // Load the information about this section's markup partial. + partial = cache.partial[section.reference()]; + + // Prepare the sample data for the partial. + data = JSON.parse(JSON.stringify(partial.data)); + if (data.modifier_class) { + data.modifier_class += modifier ? ' ' + modifier.className() : ''; + } + else { + data.modifier_class = modifier ? modifier.className() : ''; + } + + // Compile the section's markup partial into a template. + template = handlebars.compile('{{> "' + partial.name + '"}}'); + // We don't wrap the rendered template in "new handlebars.SafeString()" since + // we want the ability to display it as a code sample with {{ }} and as + // rendered HTML with {{{ }}}. + return template(data); + }); return handlebars; }; \ No newline at end of file diff --git a/index.js b/index.js index fe527be..a2f51c7 100644 --- a/index.js +++ b/index.js @@ -1,18 +1,18 @@ -var fs = require('fs'), - gulp = require('gulp'), - kss = require('kss'), - path = require('path'), - gutil = require('gulp-util'), - util = require('util'), - assign = require('object-assign'), - handlebars = require('handlebars'), - gulpless = require('gulp-less'), - sass = require('gulp-sass'), - File = require('vinyl'), - through = require('through'), - custom = [], +var fs = require('fs'), + gulp = require('gulp'), + kss = require('kss'), + path = require('path'), + gutil = require('gulp-util'), + util = require('util'), + assign = require('object-assign'), + handlebars = require('handlebars'), + gulpless = require('gulp-less'), + sass = require('gulp-sass'), + File = require('vinyl'), + through = require('through'), + custom = [], styleguide, - handlebarHelpers = require('./handlebarHelpers'); + handlebarHelpers = require('./handlebarHelpers'); module.exports = function(opt) { 'use strict'; @@ -32,17 +32,14 @@ module.exports = function(opt) { css: [], js: [] }, - cache = { - partial: {} - }; + cache = {partial: {}}; opt = assign(defaults, opt); /* Is called for each file and writes all files to buffer */ - - function bufferContents(file) { + function bufferContents(file){ if (file.isNull()) return; // ignore - if (file.isStream()) return this.emit('error', new PluginError('gulp-kss', 'Streaming not supported')); + if (file.isStream()) return this.emit('error', new PluginError('gulp-kss', 'Streaming not supported')); if (!firstFile) firstFile = file; buffer.push(file.contents.toString('utf8')); @@ -50,8 +47,8 @@ module.exports = function(opt) { function processKss() { var templatePath = path.resolve(process.cwd() + '/' + opt.template), - template = fs.readFileSync(templatePath + '/index.html', 'utf8'), - self = this; + template = fs.readFileSync(templatePath + '/index.html', 'utf8'), + self = this; template = handlebars.compile(template); @@ -117,7 +114,8 @@ module.exports = function(opt) { } } } - } else { + } + else { console.log(' - ' + partial.reference + ': inline markup'); } @@ -151,6 +149,7 @@ module.exports = function(opt) { if (fs.existsSync(opt.helpers)) { var helperFiles = fs.readdirSync(opt.helpers); helperFiles.forEach(function(fileName) { + console.log(fileName); if (path.extname(fileName) !== '.js') { return; } @@ -165,7 +164,7 @@ module.exports = function(opt) { } for (i = 0; i < rootCount; i += 1) { - childSections = styleguide.section(sectionRoots[i] + '.*'); + childSections = styleguide.section(sectionRoots[i]+'.*'); self.emit('data', generatePage(styleguide, childSections, sectionRoots[i], sectionRoots, template)); } @@ -208,7 +207,7 @@ module.exports = function(opt) { }); } - function jsonModifiers(modifiers) { + function jsonModifiers (modifiers) { return modifiers.map(function(modifier) { return { name: modifier.name(), @@ -241,33 +240,34 @@ module.exports = function(opt) { filename = 'index.html'; console.log(' - homepage'); // Ensure homepageText is a non-false value. - if (fs.existsSync(opt.template + '/styleguide.md')) { + if (fs.existsSync(opt.template + '/styleguide.md') ) { homepageText = ' ' + marked(fs.readFileSync(opt.template + '/styleguide.md', 'utf8')); } if (!homepageText) { homepageText = ' '; console.log(' ...no homepage content found in styleguide.md.'); } - } else { + } + else { filename = 'section-' + kss.KssSection.prototype.encodeReferenceURI(root) + '.html'; console.log( - ' - section ' + root + ' [', + ' - section '+root+' [', styleguide.section(root) ? styleguide.section(root).header() : 'Unnamed', ']' ); } var content = template({ - styleguide: styleguide, - sections: sections.map(function(section) { - return section.JSON(opt.custom); + styleguide: styleguide, + sections: sections.map(function(section) { + return section.JSON(opt.custom); + }), + sectionRoots: sectionRoots, + rootName: root, + homepage: homepageText, + overview: false, + styles: styles, + scripts: scripts }), - sectionRoots: sectionRoots, - rootName: root, - homepage: homepageText, - overview: false, - styles: styles, - scripts: scripts - }), filename = path.join(firstFile.base, filename), file = new File({ cwd: firstFile.cwd, @@ -280,16 +280,17 @@ module.exports = function(opt) { }; var underscoreAfter = function underscoreAfter(times, func) { - return function() { - if (--times < 1) { - return func.apply(this, arguments); - } - }; + return function() { + if (--times < 1) { + return func.apply(this, arguments); + } + }; }; var emitEnd = underscoreAfter(2, function emitEnd(self) { - self.emit('end'); + self.emit('end'); }); return through(bufferContents, processKss); -}; \ No newline at end of file +}; + diff --git a/package.json b/package.json index 6a55e90..15f4b31 100644 --- a/package.json +++ b/package.json @@ -24,6 +24,8 @@ "gulp": "~3.5.2", "gulp-util": "~2.2.14", "marked": "~0.3.1", + "object-assign": "~2.0.0", + "vinyl": "~0.4.6", "handlebars": "~2.0.0-alpha.1", "gulp-less": "~1.2.1" } From 9787dfaa5e4558baddac668192ce55091b67c74b Mon Sep 17 00:00:00 2001 From: Kevin Druff Date: Tue, 21 Apr 2015 11:09:19 -0400 Subject: [PATCH 3/7] bad package number for KSS in package.json ... updated to ~2.0.2 --- index.js | 1 - package.json | 6 ++++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/index.js b/index.js index a2f51c7..a9dd23c 100644 --- a/index.js +++ b/index.js @@ -149,7 +149,6 @@ module.exports = function(opt) { if (fs.existsSync(opt.helpers)) { var helperFiles = fs.readdirSync(opt.helpers); helperFiles.forEach(function(fileName) { - console.log(fileName); if (path.extname(fileName) !== '.js') { return; } diff --git a/package.json b/package.json index 15f4b31..49ce194 100644 --- a/package.json +++ b/package.json @@ -19,14 +19,16 @@ }, "license": "MIT", "dependencies": { - "kss": "~0.4.0", + "kss": "~2.0.2", "through": "~2.3.4", "gulp": "~3.5.2", - "gulp-util": "~2.2.14", "marked": "~0.3.1", "object-assign": "~2.0.0", "vinyl": "~0.4.6", "handlebars": "~2.0.0-alpha.1", "gulp-less": "~1.2.1" + }, + "devDependencies": { + "gulp-util": "~2.2.14" } } From 275009b2ce8ca0bbb3fc7bcda4bb1e2788d48364 Mon Sep 17 00:00:00 2001 From: Kevin Druff Date: Fri, 24 Apr 2015 13:40:35 -0400 Subject: [PATCH 4/7] had an error in which options were passed to kss.parse --- README.md | 19 +++++------ index.js | 90 +++++++++++++++++++++++++++------------------------- package.json | 16 +++++++--- 3 files changed, 66 insertions(+), 59 deletions(-) diff --git a/README.md b/README.md index 4097deb..ae5e713 100644 --- a/README.md +++ b/README.md @@ -19,14 +19,12 @@ Pipe all source files you want to document through `gulp-kss`, also the ones whi gulp.src( ['array/*.scss', 'ofSource/*.scss', 'sass/files/*.scss'] ) .pipe( gulpkss({ template: './node_modules/kss/lib/template', - kss: { - multiline: true, - typos: false - }, - custom: [], - helpers: '', - css: [], - js: [] + multiline: true, + typos: false + custom: [], + helpers: '', + css: [], + js: [] }) ) .pipe(gulp.dest('styleguide/')); @@ -35,9 +33,8 @@ gulp.src( ['array/*.scss', 'ofSource/*.scss', 'sass/files/*.scss'] ) * **template**: A path relative to your `gulpfile.js` containing a custom template (Default: `./node_modules/kss/lib/template/`) * **destination**: A path relative to your `gulpfile.js` where you would your compiled guide to live (Default: `./docs/styleguide/`) -* **kss**: kss options - * **multiline** : As far as the parser is concerned, all but the last two paragraphs (separated by two line breaks) in a block are considered to be part of the description. In the case you don't have any modifiers but a large description it'll try to pick up this scenario. This setting's enabled by default, but you can disable it by adding multiline: false to your options. - * **typos**: Thanks to [natural](https://github.com/NaturalNode/natural), `kss-node` can parse keywords phonetically rather then by their string value. In short: make a typo and the library will do its best to read it anyway. Enable this by setting typos to true in the options object. +* **multiline** : As far as the parser is concerned, all but the last two paragraphs (separated by two line breaks) in a block are considered to be part of the description. In the case you don't have any modifiers but a large description it'll try to pick up this scenario. This setting's enabled by default, but you can disable it by adding multiline: false to your options. +* **typos**: Thanks to [natural](https://github.com/NaturalNode/natural), `kss-node` can parse keywords phonetically rather then by their string value. In short: make a typo and the library will do its best to read it anyway. Enable this by setting typos to true in the options object. * **custom**: A custom property name when parsing KSS comments * **helpers**: Specify the location of custom [handlebars helpers](http://bit.ly/kss-helpers) (Default: `./lib/template/helpers`) * **css**: Specify the URL of a CSS file to include in the style guide diff --git a/index.js b/index.js index a9dd23c..24b044f 100644 --- a/index.js +++ b/index.js @@ -21,12 +21,10 @@ module.exports = function(opt) { buffer = [], defaults = { template: './node_modules/kss/lib/template', - kss: { - mask: {}, - markdown: true, - multiline: true, - typos: false - }, + mask: {}, + markdown: true, + multiline: true, + typos: false, custom: [], helpers: '', css: [], @@ -35,6 +33,11 @@ module.exports = function(opt) { cache = {partial: {}}; opt = assign(defaults, opt); + var templatePath = path.resolve(process.cwd() + '/' + opt.template), + template = fs.readFileSync(templatePath + '/index.html', 'utf8'); + template = handlebars.compile(template); + + /* Is called for each file and writes all files to buffer */ function bufferContents(file){ @@ -46,13 +49,9 @@ module.exports = function(opt) { } function processKss() { - var templatePath = path.resolve(process.cwd() + '/' + opt.template), - template = fs.readFileSync(templatePath + '/index.html', 'utf8'), - self = this; - - template = handlebars.compile(template); + var self = this; - kss.parse(buffer, opt.kss, function(err, guide) { + kss.parse(buffer, opt, function(err, guide) { if (err) { console.log('Error', error); throw err; @@ -142,9 +141,7 @@ module.exports = function(opt) { console.log('...Generating style guide sections:'); } - // Now, group all of the sections by their root - // reference, and make a page for each. - rootCount = sectionRoots.length; + handlebarHelpers(handlebars, styleguide, cache); if (fs.existsSync(opt.helpers)) { var helperFiles = fs.readdirSync(opt.helpers); @@ -154,14 +151,17 @@ module.exports = function(opt) { } opt.helpers = path.normalize(opt.helpers); opt.helpers = path.resolve(process.cwd(), opt.helpers); - var helper = require(opt.helpers + '/' + fileName); if (typeof helper.register === 'function') { - helper.register(handlebars); + helper.register(handlebars, styleguide); } }); } + // Now, group all of the sections by their root + // reference, and make a page for each. + rootCount = sectionRoots.length; + for (i = 0; i < rootCount; i += 1) { childSections = styleguide.section(sectionRoots[i]+'.*'); self.emit('data', generatePage(styleguide, childSections, sectionRoots[i], sectionRoots, template)); @@ -192,29 +192,29 @@ module.exports = function(opt) { }); } - function jsonSections(sections) { - return sections.map(function(section) { - return { - header: section.header(), - description: section.description(), - reference: section.reference(), - depth: section.data.refDepth, - deprecated: section.deprecated(), - experimental: section.experimental(), - modifiers: jsonModifiers(section.modifiers()) - }; - }); - } - - function jsonModifiers (modifiers) { - return modifiers.map(function(modifier) { - return { - name: modifier.name(), - description: modifier.description(), - className: modifier.className() - }; - }); - } + // function jsonSections(sections) { + // return sections.map(function(section) { + // return { + // header: section.header(), + // description: section.description(), + // reference: section.reference(), + // depth: section.data.refDepth, + // deprecated: section.deprecated(), + // experimental: section.experimental(), + // modifiers: jsonModifiers(section.modifiers()) + // }; + // }); + // } + + // function jsonModifiers (modifiers) { + // return modifiers.map(function(modifier) { + // return { + // name: modifier.name(), + // description: modifier.description(), + // className: modifier.className() + // }; + // }); + // } function generatePage(styleguide, sections, root, sectionRoots, template) { var files, @@ -223,9 +223,6 @@ module.exports = function(opt) { styles = opt.css, scripts = opt.js; - var args = { - styleguide: styleguide - } // Create the HTML to load the optional CSS and JS. for (var key in opt.css) { styles = styles + '\n'; @@ -255,6 +252,13 @@ module.exports = function(opt) { ']' ); } + // console.log(opt.custom); + // console.log( + // sections.map(function(section) { + // console.log(section); + // return section.JSON(opt.custom); + // }) + // ); var content = template({ styleguide: styleguide, sections: sections.map(function(section) { diff --git a/package.json b/package.json index 49ce194..7685071 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "gulp-kss", - "version": "0.2.0", + "version": "2.0.2", "description": "Gulp plugin for KSS (Knyle Style Sheets) documentation generation", "repository": { "type": "git", @@ -13,10 +13,16 @@ "generator", "gulp" ], - "contributor": { - "name": "Philipp Schächtele", - "email": "philipp@digitalwerft.com" - }, + "contributors": [ + { + "name": "Philipp Schächtele", + "email": "philipp@digitalwerft.com" + }, + { + "name": "Kevin Druff", + "email": "kevin.druff@gmail.com" + } + ], "license": "MIT", "dependencies": { "kss": "~2.0.2", From ac61ea89ddcd16783e74a386f2df1c8370cec5a2 Mon Sep 17 00:00:00 2001 From: Kevin Druff Date: Thu, 27 Aug 2015 15:47:56 -0400 Subject: [PATCH 5/7] Update index.js had missed adding marked to the variables in index.js --- index.js | 1 + 1 file changed, 1 insertion(+) diff --git a/index.js b/index.js index 24b044f..2669116 100644 --- a/index.js +++ b/index.js @@ -9,6 +9,7 @@ var fs = require('fs'), gulpless = require('gulp-less'), sass = require('gulp-sass'), File = require('vinyl'), + marked = require('marked'), through = require('through'), custom = [], styleguide, From 38881c496bc13c7b635b13de817f03b3562c29a6 Mon Sep 17 00:00:00 2001 From: Kevin Druff Date: Thu, 27 Aug 2015 15:51:47 -0400 Subject: [PATCH 6/7] Update index.js re-working the path for default template. --- index.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.js b/index.js index 2669116..aecce10 100644 --- a/index.js +++ b/index.js @@ -21,7 +21,7 @@ module.exports = function(opt) { firstFile = null, buffer = [], defaults = { - template: './node_modules/kss/lib/template', + template: './node_modules/gulp-kss/node_modules/kss/lib/template', mask: {}, markdown: true, multiline: true, From e19800c9f0c754e5f41a88e9d82804ab5d2ba9af Mon Sep 17 00:00:00 2001 From: Anders Olsen Sandvik Date: Thu, 17 Sep 2015 15:21:08 +0200 Subject: [PATCH 7/7] Remove unused dependencie --- index.js | 1 - 1 file changed, 1 deletion(-) diff --git a/index.js b/index.js index aecce10..494536c 100644 --- a/index.js +++ b/index.js @@ -2,7 +2,6 @@ var fs = require('fs'), gulp = require('gulp'), kss = require('kss'), path = require('path'), - gutil = require('gulp-util'), util = require('util'), assign = require('object-assign'), handlebars = require('handlebars'),