Merge pull request #137 from Financial-Times/sassdoc

Added sassdocs

README.md

@@ -30,7 +30,7 @@ Runs:
 
 The versions that are installed and supported are:
 
-* SASS: '3.3.14' _(SASS 3.4.x is currently not supported and you may not get the desired result)_
+* Sass: '3.3.14' _(Sass 3.4.x is currently not supported and you may not get the desired result)_
 * scss-lint: '0.27.0'
 * JSHint: '2.5.6'
 * Bower: '1.3.12'
@@ -55,22 +55,22 @@ Runs:
 	- ignoreMissing: See [browserify documentation](https://github.com/substack/node-browserify#usage)
 	- standalone: See [browserify documentation](https://github.com/substack/node-browserify#usage)
 * __sass(gulp, config)__ Config accepts:
-	- sass: `String` Path to your main SASS file. (Default: './main.scss' and checks your bower.json to see if it's in its main key) 
+	- sass: `String` Path to your main Sass file. (Default: './main.scss' and checks your bower.json to see if it's in its main key) 
 	- autoprefixerBrowsers: `Array` An array of strings of [browser names for autoprefixer](https://github.com/postcss/autoprefixer#browsers) to check what prefixes it needs. (Default: `["> 1%", "last 2 versions", "ie > 6", "ff ESR"]`)
 	- autoprefixerCascade: `Boolean` Whether autoprefixer should display CSS prefixed properties [cascaded](https://github.com/postcss/autoprefixer#visual-cascade) (Default: false)
 	- autoprefixerRemove: `Boolean` Remove unneeded prefixes (Default: true)
 	- buildCss: `String` Name of the built CSS bundle. (Default: 'main.css')
 	- buildFolder: `String` Path to directory where the built file will be created. (Default: './build/')
-	- env: `String` It can be either 'production' or 'development'. If it's 'production', it will compile the SASS file with the 'compressed' style option and will also run [csso](https://github.com/css/csso). (Default: 'development')
+	- env: `String` It can be either 'production' or 'development'. If it's 'production', it will compile the Sass file with the 'compressed' style option and will also run [csso](https://github.com/css/csso). (Default: 'development')
 
 	_(Sourcemaps aren't generated as this feature is incompatible with csso. We will revisit this when [gulp-ruby-sass](https://github.com/sindresorhus/gulp-ruby-sass) 1.0 is released)_
 
 ### test
 
-Tests [silent compilation](http://origami.ft.com/docs/syntax/scss/#silent-styles).  If your SASS contains a `$<module-name>-is-silent` variable, then runs:
+Tests [silent compilation](http://origami.ft.com/docs/syntax/scss/#silent-styles).  If your Sass contains a `$<module-name>-is-silent` variable, then runs:
 
-* __silentCompilation(gulp)__ Check the SASS outputs no CSS by default
-* __silentCompilation(gulp)__ Check the SASS outputs some CSS with `$<module-name>-is-silent` set to false
+* __silentCompilation(gulp)__ Check the Sass outputs no CSS by default
+* __silentCompilation(gulp)__ Check the Sass outputs some CSS with `$<module-name>-is-silent` set to false
 * __npmTest()__ Runs 'npm test', so whatever test script that you have in you `package.json` will be executed
 
 ### verify
@@ -80,7 +80,7 @@ Lints JavaScript and SCSS against Origami coding standards (see standards for [S
 Runs:
 
 * __scssLint(gulp, config)__ Config accepts:
-	- sass: `String` Path to your main SASS file. (Default: './main.scss' and checks your bower.json to see if it's in its main key)
+	- sass: `String` Path to your main Sass file. (Default: './main.scss' and checks your bower.json to see if it's in its main key)
 	- scssLintPath: `String` Path to your custom 'scss-lint.yml' config file. (Default: 'origami-build-tools/config/scss-lint.yml') _This may be set for product development, but developers of Origami-compliant components are required to accept the default_
 * __jsHint(gulp, config)__ Config accepts:
 	- js: `String` Path to your main Javascript file. (Default: './main.js' and checks your bower.json to see if it's in its main key)
@@ -105,10 +105,20 @@ Runs:
 
 Build service demos consist of only HTML, with build service URLs for static resources, and are created in `demos/`
 
-Local demos consist of HTML, CSS and JS (if SASS & JS exists), and are created in `demos/local/`. These files should not be committed. It is recommended to add demos/local/ to your `.gitignore`.
+Local demos consist of HTML, CSS and JS (if Sass & JS exists), and are created in `demos/local/`. These files should not be committed. It is recommended to add demos/local/ to your `.gitignore`.
 
 _(Sourcemaps aren't generated as this feature is incompatible with csso. We will revisit this when [gulp-ruby-sass](https://github.com/sindresorhus/gulp-ruby-sass) 1.0 is released)_
 
+### docs
+
+Build component documentation into the `docs` directory.
+
+Runs:
+
+* __sassDoc(gulp, config)__ Sass documentation is built using [SassDoc](http://sassdoc.com/). Config accepts:
+	- sassDir: `String` Path to the directory where you main Sass file is. (Default: '.')
+	- Any option supported by the [SassDoc gulp plugin](http://sassdoc.com/gulp/#options)
+
 ## gulpfile usage
 
 Use the build tools in your own Gulp file to incorporate the Origami build process into a *product* (don't use this method if you are building an Origami component). An in depth explanation of how to use the `origami-build-tools` in your product to build Origami modules can be found in the [Origami spec](http://origami.ft.com/docs/developer-guide/building-modules/).  

lib/origami-build-tools.js

@@ -7,7 +7,8 @@ var update = require('./helpers/update-notifier'),
 	installer = require('./tasks/install'),
 	builder = require('./tasks/build'),
 	tester = require('./tasks/test'),
-	demoer = require('./tasks/demo');
+	demoer = require('./tasks/demo'),
+	docs = require('./tasks/docs');
 
 update();
 
@@ -16,6 +17,7 @@ var tasks = {
 	'build': builder,
 	'test': tester,
 	'demo': demoer,
+	'docs': docs,
 	'verify': verifier
 };
 

lib/tasks/build.js

@@ -66,39 +66,40 @@ module.exports.sass = function(gulp, config) {
 	config = config || {};
 	var src = config.sass || files.getMainSassPath() || null;
 	if (src) {
-			var destFolder = config.buildFolder || files.getBuildFolderPath(),
-				dest = config.buildCss || 'main.css';
-			log.secondary("Compiling " + src);
+		var destFolder = config.buildFolder || files.getBuildFolderPath();
+		var dest = config.buildCss || 'main.css';
 
-			config.env = config.env || 'development';
+		log.secondary("Compiling " + src);
 
-			var sassConfig = {
-				loadPath: ['.', 'bower_components']
-			};
-
-			var autoprefixerConfig = {
-				browsers: config.autoprefixerBrowsers || ['> 1%', 'last 2 versions', 'ie > 6', 'ff ESR'],
-				cascade: config.autoprefixerCascade || false,
-				remove: config.autoprefixerRemove || true
-			};
+		config.env = config.env || 'development';
 
-			if (config.env === 'production') {
-				sassConfig.style = 'compressed';
-			}
-			// Sourcemaps aren't compatible with csso, we'll look for a work-around when gulp-ruby-sass 1.0 is released
-			// if (config.sourcemap) {
-			//     sassConfig.sourcemap = config.sourcemap;
-			// }
-			// if (config.sourcemapPath) {
-			//     sassConfig.sourcemapPath = config.sourcemapPath;
-			// }
-			return gulp.src(src)
-				.pipe(sass(sassConfig))
-				.pipe(autoprefixer(autoprefixerConfig))
-				.pipe(gulpif(config.env === 'production', csso()))
-				.pipe(rename(dest))
-				.pipe(gulp.dest(destFolder))
-				.on('error', function(err) { console.log(err.message);});
+		var sassConfig = {
+			loadPath: ['.', 'bower_components']
+		};
+
+		var autoprefixerConfig = {
+			browsers: config.autoprefixerBrowsers || ['> 1%', 'last 2 versions', 'ie > 6', 'ff ESR'],
+			cascade: config.autoprefixerCascade || false,
+			remove: config.autoprefixerRemove || true
+		};
+
+		if (config.env === 'production') {
+			sassConfig.style = 'compressed';
+		}
+		// Sourcemaps aren't compatible with csso, we'll look for a work-around when gulp-ruby-sass 1.0 is released
+		// if (config.sourcemap) {
+		//     sassConfig.sourcemap = config.sourcemap;
+		// }
+		// if (config.sourcemapPath) {
+		//     sassConfig.sourcemapPath = config.sourcemapPath;
+		// }
+		return gulp.src(src)
+			.pipe(sass(sassConfig))
+			.pipe(autoprefixer(autoprefixerConfig))
+			.pipe(gulpif(config.env === 'production', csso()))
+			.pipe(rename(dest))
+			.pipe(gulp.dest(destFolder))
+			.on('error', function(err) { console.log(err.message);});
 	}
 };
 

lib/tasks/docs.js

@@ -0,0 +1,24 @@
+'use strict';
+
+var path = require('path');
+var sassdoc = require('gulp-sassdoc');
+var extend = require('node.extend');
+var files = require('../helpers/files');
+
+module.exports = function(gulp, config) {
+	module.exports.sassDoc(gulp, config);
+};
+
+module.exports.sassDoc = function(gulp, config) {
+	config = config || {};
+	var src = config.sassDir || '.';
+	var sassdocConfig = {
+		dest: path.join(src, '/docs/sass')
+	};
+
+	return gulp.src(src)
+		.pipe(sassdoc(extend(true, {}, sassdocConfig, config)));
+};
+
+module.exports.watchable = true;
+module.exports.description = 'Builds the documentation in the docs directory';

package.json

@@ -1,46 +1,47 @@
 {
-	"name": "origami-build-tools",
-	"preferGlobal": true,
-	"version": "2.3.0",
-	"description": "Origami component development tools.",
-	"main": "./lib/origami-build-tools",
-	"bin": {
-		"origami-build-tools": "./lib/origami-build-tools-cli.js"
-	},
-	"private": true,
-	"engines": {
-		"node": ">= 0.10.0"
-	},
-	"dependencies": {
-		"bower-config": "^0.5.2",
-		"browserify": "~3.44.2",
-		"colors": "^0.6.2",
-		"configstore": "^0.3.1",
-		"debowerify": "git+https://github.com/Financial-Times/debowerify.git",
-		"es6-promise": "^1.0.0",
-		"findit": "^1.1.1",
-		"gulp": "^3.8.7",
-		"gulp-autoprefixer": "^2.0.0",
-		"gulp-csso": "^0.2.9",
-		"gulp-if": "^1.2.5",
-		"gulp-jshint": "^1.8.4",
-		"gulp-lintspaces": "^0.2.2",
-		"gulp-mustache": "^0.4.0",
-		"gulp-rename": "^1.2.0",
-		"gulp-ruby-sass": "^0.7.1",
-		"gulp-scss-lint": "^0.1.3",
-		"gulp-streamify": "0.0.5",
-		"gulp-uglify": "^1.0.1",
-		"gulp-util": "^3.0.1",
-		"gulp-webserver": "^0.8.3",
-		"minimist": "0.0.8",
-		"node.extend": "^1.0.9",
-		"npmconf": "^1.1.5",
-		"portfinder": "0.2.x",
-		"semver": "^2.2.1",
-		"textrequireify": "^1.0.0",
-		"through2": "^0.6.2",
-		"vinyl-source-stream": "^1.0.0",
-		"which": "^1.0.5"
-	}
+  "name": "origami-build-tools",
+  "preferGlobal": true,
+  "version": "2.3.0",
+  "description": "Origami component development tools.",
+  "main": "./lib/origami-build-tools",
+  "bin": {
+    "origami-build-tools": "./lib/origami-build-tools-cli.js"
+  },
+  "private": true,
+  "engines": {
+    "node": ">= 0.10.0"
+  },
+  "dependencies": {
+    "bower-config": "^0.5.2",
+    "browserify": "~3.44.2",
+    "colors": "^0.6.2",
+    "configstore": "^0.3.1",
+    "debowerify": "git+https://github.com/Financial-Times/debowerify.git",
+    "es6-promise": "^1.0.0",
+    "findit": "^1.1.1",
+    "gulp": "^3.8.7",
+    "gulp-autoprefixer": "^2.0.0",
+    "gulp-csso": "^0.2.9",
+    "gulp-if": "^1.2.5",
+    "gulp-jshint": "^1.8.4",
+    "gulp-lintspaces": "^0.2.2",
+    "gulp-mustache": "^0.4.0",
+    "gulp-rename": "^1.2.0",
+    "gulp-ruby-sass": "^0.7.1",
+    "gulp-sassdoc": "^1.1.1",
+    "gulp-scss-lint": "^0.1.3",
+    "gulp-streamify": "0.0.5",
+    "gulp-uglify": "^1.0.1",
+    "gulp-util": "^3.0.1",
+    "gulp-webserver": "^0.8.3",
+    "minimist": "0.0.8",
+    "node.extend": "^1.0.9",
+    "npmconf": "^1.1.5",
+    "portfinder": "0.2.x",
+    "semver": "^2.2.1",
+    "textrequireify": "^1.0.0",
+    "through2": "^0.6.2",
+    "vinyl-source-stream": "^1.0.0",
+    "which": "^1.0.5"
+  }
 }