Docs: Split API docs into separate markdown files

Author: phated

docs/API.md

@@ -8,7 +8,7 @@ sidebar_label: Docs
 # gulp documentation
 
 * [Getting Started](getting-started/) - Get started with gulp
-* [API documentation](API.md) - The programming interface, defined
+* [API documentation](api/) - The programming interface, defined
 * [CLI documentation](CLI.md) - Learn how to call tasks and use compilers
 * [Writing a Plugin](writing-a-plugin/) - The essentials of writing a gulp plugin
 * [Why Use Pump?](why-use-pump/README.md) - Why to use the `pump` module instead of calling `.pipe` yourself

docs/README.md

@@ -0,0 +1,19 @@
+<!-- front-matter
+id: api-toc
+title: API Table of Contents
+hide_title: true
+sidebar_label: api-toc
+-->
+
+## gulp API docs
+
+* [gulp.src](src.md) - Emit files matching one or more globs
+* [gulp.dest](dest.md) - Write files to directories
+* [gulp.symlink](symlink.md) - Write files to symlinks
+* [gulp.task](task.md) - Define tasks
+* [gulp.lastRun](lastRun.md) - Get timestamp of last successful run
+* [gulp.parallel](parallel.md) - Run tasks in parallel
+* [gulp.series](series.md) - Run tasks in series
+* [gulp.watch](watch.md) - Do something when a file changes
+* [gulp.tree](tree.md) - Get the tree of tasks
+* [gulp.registry](registry.md) - Get or set the task registry

docs/api/README.md

@@ -0,0 +1,66 @@
+<!-- front-matter
+id: api-dest
+title: dest()
+hide_title: true
+sidebar_label: dest()
+-->
+
+# `gulp.dest(path[, options])`
+
+Can be piped to and it will write files. Re-emits all data passed to it so you
+can pipe to multiple folders. Folders that don't exist will be created.
+
+```javascript
+gulp.src('./client/templates/*.pug')
+  .pipe(pug())
+  .pipe(gulp.dest('./build/templates'))
+  .pipe(minify())
+  .pipe(gulp.dest('./build/minified_templates'));
+```
+
+The write path is calculated by appending the file relative path to the given
+destination directory. In turn, relative paths are calculated against
+the file base. See `gulp.src` above for more info.
+
+## path
+Type: `String` or `Function`
+
+The path (output folder) to write files to. Or a function that returns it,
+the function will be provided a [vinyl File instance].
+
+## options
+Type: `Object`
+
+### options.cwd
+Type: `String`
+
+Default: `process.cwd()`
+
+`cwd` for the output folder, only has an effect if provided output folder is
+relative.
+
+### options.mode
+Type: `String` or `Number`
+
+Default: the mode of the input file (file.stat.mode) or the process mode
+if the input file has no mode property.
+
+Octal permission specifying the mode the files should be created with: e.g.
+`"0744"`, `0744` or `484` (`0744` in base 10).
+
+### options.dirMode
+Type: `String` or `Number`
+
+Default: Default is the process mode.
+
+Octal permission specifying the mode the directory should be created with: e.g.
+`"0755"`, `0755` or `493` (`0755` in base 10).
+
+### options.overwrite
+Type: `Boolean`
+
+Default: `true`
+
+Specify if existing files with the same path should be overwritten or not.
+
+[vinyl File instance]: https://github.com/gulpjs/vinyl

docs/api/dest.md

@@ -0,0 +1,43 @@
+<!-- front-matter
+id: api-lastRun
+title: lastRun()
+hide_title: true
+sidebar_label: lastRun()
+-->
+
+# `gulp.lastRun(taskName, [timeResolution])`
+
+Returns the timestamp of the last time the task ran successfully. The time
+will be the time the task started. Returns `undefined` if the task has
+not run yet.
+
+## taskName
+
+Type: `String`
+
+The name of the registered task or of a function.
+
+## timeResolution
+
+Type: `Number`.
+
+Default: `1000` on node v0.10, `0` on node v0.12 (and iojs v1.5).
+
+Set the time resolution of the returned timestamps. Assuming
+the task named "someTask" ran at `1426000004321`:
+
+- `gulp.lastRun('someTask', 1000)` would return `1426000004000`.
+- `gulp.lastRun('someTask', 100)` would return `1426000004300`.
+
+`timeResolution` allows you to compare a run time to a file [mtime stat][fs stats]
+attribute. This attribute time resolution may vary depending of the node version
+and the file system used:
+
+- on node v0.10, a file [mtime stat][fs stats] time resolution of any files will be 1s at best;
+- on node v0.12 and iojs v1.5, 1ms at best;
+- for files on FAT32, the mtime time resolution is 2s;
+- on HFS+ and Ext3, 1s;
+- on NTFS, 1s on node v0.10, 100ms on node 0.12;
+- on Ext4, 1s on node v0.10, 1ms on node 0.12.
+
+[fs stats]: https://nodejs.org/api/fs.html#fs_class_fs_stats

docs/api/lastRun.md

@@ -0,0 +1,40 @@
+<!-- front-matter
+id: api-parallel
+title: parallel()
+hide_title: true
+sidebar_label: parallel()
+-->
+
+# `gulp.parallel(...tasks)`
+
+Takes a number of task names or functions and returns a function of the composed
+tasks or functions.
+
+When using task names, the task should already be registered.
+
+When the returned function is executed, the tasks or functions will be executed
+in parallel, all being executed at the same time. If an error occurs,
+all execution will complete.
+
+```js
+gulp.task('one', function(done) {
+  // do stuff
+  done();
+});
+
+gulp.task('two', function(done) {
+  // do stuff
+  done();
+});
+
+gulp.task('default', gulp.parallel('one', 'two', function(done) {
+  // do more stuff
+  done();
+}));
+```
+
+## tasks
+Type: `Array`, `String` or `Function`
+
+A task name, a function or an array of either.
+

docs/api/parallel.md

@@ -0,0 +1,64 @@
+<!-- front-matter
+id: api-registry
+title: registry()
+hide_title: true
+sidebar_label: registry()
+-->
+
+# `gulp.registry([registry])`
+
+Get or set the underlying task registry. Inherited from [undertaker]; see the undertaker documention on [registries](https://github.com/phated/undertaker#registryregistryinstance). Using this, you can change registries that enhance gulp in different ways. Utilizing a custom registry has at least three use cases:
+
+- [Sharing tasks](https://github.com/phated/undertaker#sharing-tasks)
+- [Sharing functionality](https://github.com/phated/undertaker#sharing-functionalities) (e.g. you could override the task prototype to add some additional logging, bind task metadata or include some config settings.)
+- Handling other behavior that hooks into the registry lifecycle (see [gulp-hub](https://github.com/frankwallis/gulp-hub) for an example)
+
+To build your own custom registry see the [undertaker documentation on custom registries](https://github.com/phated/undertaker#custom-registries).
+
+## registry
+
+A registry instance. When passed in, the tasks from the current registry will be transferred to the new registry and then current registry will be replaced with the new registry.
+
+## Example
+
+This example shows how to create and use a simple custom registry to add tasks.
+
+```js
+//gulpfile.js
+var gulp = require('gulp');
+
+var companyTasks = require('./myCompanyTasksRegistry.js');
+
+gulp.registry(companyTasks);
+
+gulp.task('one', gulp.parallel('someCompanyTask', function(done) {
+  console.log('in task one');
+  done();
+}));
+```
+
+```js
+//myCompanyTasksRegistry.js
+var util = require('util');
+
+var DefaultRegistry = require('undertaker-registry');
+
+function MyCompanyTasksRegistry() {
+  DefaultRegistry.call(this);
+}
+util.inherits(MyCompanyTasksRegistry, DefaultRegistry);
+
+MyCompanyTasksRegistry.prototype.init = function(gulp) {
+  gulp.task('clean', function(done) {
+    done();
+  });
+  gulp.task('someCompanyTask', function(done) {
+    console.log('performing some company task.');
+    done();
+  });
+};
+
+module.exports = new MyCompanyTasksRegistry();
+```
+
+[undertaker]: https://github.com/gulpjs/undertaker

docs/api/registry.md

@@ -0,0 +1,39 @@
+<!-- front-matter
+id: api-series
+title: series()
+hide_title: true
+sidebar_label: series()
+-->
+
+# `gulp.series(...tasks)`
+
+Takes a number of task names or functions and returns a function of the composed
+tasks or functions.
+
+When using task names, the task should already be registered.
+
+When the returned function is executed, the tasks or functions will be executed
+in series, each waiting for the prior to finish. If an error occurs,
+execution will stop.
+
+```js
+gulp.task('one', function(done) {
+  // do stuff
+  done();
+});
+
+gulp.task('two', function(done) {
+  // do stuff
+  done();
+});
+
+gulp.task('default', gulp.series('one', 'two', function(done) {
+  // do more stuff
+  done();
+}));
+```
+
+## tasks
+Type: `Array`, `String` or `Function`
+
+A task name, a function or an array of either.