Merge pull request #10 from Microsoft/nickpape/update-custom-task-fun…

…ction-and-docs

Update documentation and rename defineTask->subTask

README.md

@@ -64,11 +64,19 @@ let karma = require('gulp-core-build-karma').default;
 let webpack = require('gulp-core-build-webpack').default;
 let serve = require('gulp-core-build-serve').default;
 
+// Shorthand for defining custom subtasks
+// The proper method for this is to introduce a new package which exports a class that extends GulpTask
+// However, this shorthand allows an easy way to introduce one-off subtasks directly in the gulpfile
+let helloWorldSubtask = build.subTask('do-hello-world-subtask', function(gulp, buildOptions, done) {
+  this.log('Hello, World!'); // use functions from GulpTask
+});
+
 // Define gulp tasks.
-let buildTasks = build.task('build', build.parallel(lint, typescript, sass));
+let buildTasks = build.task('build', build.parallel(helloWorldSubtask, lint, typescript, sass));
 let testTasks = build.task('test', build.serial(buildTasks, karma));
 let bundleTasks = build.task('bundle', build.serial(buildTasks, webpack));
 let serveTasks = build.task('serve', build.serial(bundleTasks, serve));
+let helloWorldTasks = build.task('hello-world', helloWorldSubtask);
 let defaultTasks = build.task('default', testTasks);
 
 // Tell the build to set up gulp tasks with the given gulp instance.
@@ -81,10 +89,13 @@ Once this is set up, you should be able to execute the gulp tasks and they shoul
 
 | Task name | Description |
 | --------- | ----------- |
-| gulp-core-build-typescript | Builds and lints typescript. |
-| gulp-core-build-sass | Compiles sass into css, into js modules, that are theme friendly. |
-| gulp-core-build-webpack | Runs webpack given a config, and outputs libraries plus the stats and logging. |
-| gulp-core-build-serve | Sets up a server and live reload for a quick dev loop. |
+| [gulp-core-build-typescript](https://www.npmjs.com/package/@microsoft/gulp-core-build-typescript) | Builds and lints typescript. |
+| [gulp-core-build-sass](https://www.npmjs.com/package/@microsoft/gulp-core-build) | Compiles sass into css, into js modules, that are theme friendly. |
+| [gulp-core-build-webpack](https://www.npmjs.com/package/@microsoft/gulp-core-build-webpack) | Runs webpack given a config, and outputs libraries plus the stats and logging. |
+| [gulp-core-build-serve](https://www.npmjs.com/package/@microsoft/gulp-core-build-serve) | Sets up a server and live reload for a quick dev loop. |
+| [gulp-core-build-karma](https://www.npmjs.com/package/@microsoft/gulp-core-build-karma) | Runs unit tests in a browser using [Karma](https://www.npmjs.com/package/karma) |
+| [gulp-core-build-mocha](https://www.npmjs.com/package/@microsoft/gulp-core-build-mocha) | Runs unit tests in a NodeJS environment with [Mocha](https://www.npmjs.com/package/mocha) |
+| [sp-build-core-tasks](https://www.npmjs.com/package/@microsoft/sp-build-core-tasks) | Special tasks for developing with the SharePoint Framework (SPFx) |
 
 # API
 
@@ -100,6 +111,14 @@ Runs a given list of tasks in parallel execution order.
 
 Runs a given list of tasks in serial execution order.
 
+## subtask(name, fn)
+
+Creates a subtask (which is not registered directly with gulp, use `task()` for that) which can be
+used with parallel and serial. The `this` variable in the callback function will be an instance of a `GulpTask`.
+
+`fn` should be a function which accepts 3 parameters: a `gulp` instance, the build configuration
+object, and an optional callback function to signify subtask completion.
+
 ## initialize(gulpInstance, [buildOtions])
 
 Registers the gulp tasks.
@@ -124,6 +143,21 @@ build.initializeTasks(
 
 # Defining a custom task
 
+The `subtask()` function is used to define a custom task. For example,
+you could create the following subtask, which is registered to the command
+`gulp hello-world`:
+
+```javascript
+let helloWorldSubtask = build.subTask('do-hello-world-subtask', function(gulp, buildOptions, done) {
+  this.log('Hello, World!'); // use functions from GulpTask
+});
+
+// Register the task with gulp command line
+let helloWorldTask = build.task('hello-world', helloWorldSubtask);
+```
+
+Note that the command `gulp do-hello-world-subtask` would error.
+
 
 # License
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/gulp-core-build",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "description": "Core gulp build tasks for building typescript, html, less, etc.",
   "repository": {
     "type": "git",

src/index.ts

@@ -121,14 +121,14 @@ class CustomTask extends GulpTask<void> {
 }
 
 /**
- * Creates a new task from a function callback. Useful as a shorthand way
+ * Creates a new subtask from a function callback. Useful as a shorthand way
  * of defining tasks directly in a gulpfile.
  *
  * @param {string} taskName - the name of the task, appearing in build logs
  * @param {boolean} addCommandLine - true if this task should be registered to the command line
  * @param {ICustomGulpTask} fn - the callback function to execute when this task runs
  */
-export function defineTask(taskName: string, addCommandLine: boolean, fn: ICustomGulpTask): IExecutable {
+export function subTask(taskName: string, fn: ICustomGulpTask): IExecutable {
   const customTask: CustomTask = new CustomTask(taskName, fn);
   return customTask;
 }