diff --git a/README.md b/README.md index 1b85b4f1..21d86bb9 100644 --- a/README.md +++ b/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 `$-is-silent` variable, then runs: +Tests [silent compilation](http://origami.ft.com/docs/syntax/scss/#silent-styles). If your Sass contains a `$-is-silent` variable, then runs: -* __silentCompilation(gulp)__ Check the SASS outputs no CSS by default -* __silentCompilation(gulp)__ Check the SASS outputs some CSS with `$-is-silent` set to false +* __silentCompilation(gulp)__ Check the Sass outputs no CSS by default +* __silentCompilation(gulp)__ Check the Sass outputs some CSS with `$-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/). diff --git a/lib/origami-build-tools.js b/lib/origami-build-tools.js index ee1ee7d7..e46f76ac 100755 --- a/lib/origami-build-tools.js +++ b/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 }; diff --git a/lib/tasks/build.js b/lib/tasks/build.js index b4edfe91..dfba7105 100644 --- a/lib/tasks/build.js +++ b/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);}); } }; diff --git a/lib/tasks/docs.js b/lib/tasks/docs.js new file mode 100644 index 00000000..058d9c22 --- /dev/null +++ b/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'; diff --git a/package.json b/package.json index 0878b849..71cabad3 100644 --- a/package.json +++ b/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" + } }