Merge pull request #1010 from SyntaxRules/patch-1

docs(gulp.tree): document gulp.tree API
gulpjs · Apr 15, 2015 · d6eda3d · d6eda3d
2 parents b477a4d + 3763556
commit d6eda3d
Show file tree

Hide file tree

Showing 2 changed files with 220 additions and 0 deletions.
diff --git a/docs/API.md b/docs/API.md
@@ -506,6 +506,154 @@ Type: String
 
 The path to the file that triggered the event.
 
+### gulp.tree(options)
+
+Returns the tree of tasks. Inherited from [undertaker]. See the [undertaker docs for this function](https://github.com/phated/undertaker#treeoptions--object).
+
+#### options
+Type: Object
+
+Options to pass to [undertaker].
+
+##### options.deep
+Type: `Boolean`
+
+Default: `false`
+
+If set to true whole tree should be returned.
+
+#### Example gulpfile
+
+```js
+gulp.task('one', function(done) {
+  // do stuff
+  done();
+});
+
+gulp.task('two', function(done) {
+  // do stuff
+  done();
+});
+
+gulp.task('three', function(done) {
+  // do stuff
+  done();
+});
+
+gulp.task('four', gulp.series('one', 'two'));
+
+gulp.task('five',
+  gulp.series('four',
+    gulp.parallel('three', function(done) {
+      // do more stuff
+      done();
+    })
+  )
+);
+```
+
+#### Example tree output
+
+```js
+gulp.tree()
+
+// output: [ 'one', 'two', 'three', 'four', 'five' ]
+
+gulp.tree({ deep: true })
+
+/*output: [
+   {
+      "label":"one",
+      "type":"task",
+      "nodes":[]
+   },
+   {
+      "label":"two",
+      "type":"task",
+      "nodes":[]
+   },
+   {
+      "label":"three",
+      "type":"task",
+      "nodes":[]
+   },
+   {
+      "label":"four",
+      "type":"task",
+      "nodes":[
+          {
+            "label":"<series>",
+            "type":"function",
+            "nodes":[
+               {
+                  "label":"one",
+                  "type":"task",
+                  "nodes":[]
+               },
+               {
+                  "label":"two",
+                  "type":"task",
+                  "nodes":[]
+               }
+            ]
+         }
+      ]
+   },
+   {
+      "label":"five",
+      "type":"task",
+      "nodes":[
+         {
+            "label":"<series>",
+            "type":"function",
+            "nodes":[
+               {
+                  "label":"four",
+                  "type":"task",
+                  "nodes":[
+                     {
+                        "label":"<series>",
+                        "type":"function",
+                        "nodes":[
+                           {
+                              "label":"one",
+                              "type":"task",
+                              "nodes":[]
+                           },
+                           {
+                              "label":"two",
+                              "type":"task",
+                              "nodes":[]
+                           }
+                        ]
+                     }
+                  ]
+               },
+               {
+                  "label":"<parallel>",
+                  "type":"function",
+                  "nodes":[
+                     {
+                        "label":"three",
+                        "type":"task",
+                        "nodes":[]
+                     },
+                     {
+                        "label":"<anonymous>",
+                        "type":"function",
+                        "nodes":[]
+                     }
+                  ]
+               }
+            ]
+         }
+      ]
+   }
+]
+*/
+```
+
+
 [Function.name]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/name
 [gaze]: https://github.com/shama/gaze
 [glob-stream]: https://github.com/wearefractal/glob-stream

diff --git a/docs/CLI.md b/docs/CLI.md
@@ -24,3 +24,75 @@ Tasks can be executed by running `gulp <task> <othertask>`. Just running `gulp`
 ### Compilers
 
 You can find a list of supported languages at [interpret](https://github.com/tkellen/node-interpret#jsvariants). If you would like to add support for a new language send pull request/open issues there.
+
+### Examples
+
+#### Example gulpfile
+
+```js
+gulp.task('one', function(done) {
+  // do stuff
+  done();
+});
+
+gulp.task('two', function(done) {
+  // do stuff
+  done();
+});
+
+gulp.task('three', three);
+
+function three(done) {
+  done();
+}
+three.description = "This is the description of task three";
+
+gulp.task('four', gulp.series('one', 'two'));
+
+gulp.task('five',
+  gulp.series('four',
+    gulp.parallel('three', function(done) {
+      // do more stuff
+      done();
+    })
+  )
+);
+```
+
+### `-T` or `--tasks`
+
+Command: `gulp -T` or `gulp --tasks`
+
+Output:
+```shell
+[20:58:55] Tasks for ~\exampleProject\gulpfile.js
+[20:58:55] ├── one
+[20:58:55] ├── two
+[20:58:55] ├── three                                         This is the description of task three
+[20:58:55] ├─┬ four
+[20:58:55] │ └─┬ <series>
+[20:58:55] │   ├── one
+[20:58:55] │   └── two
+[20:58:55] ├─┬ five
+[20:58:55] │ └─┬ <series>
+[20:58:55] │   ├─┬ four
+[20:58:55] │   │ └─┬ <series>
+[20:58:55] │   │   ├── one
+[20:58:55] │   │   └── two
+[20:58:55] │   └─┬ <parallel>
+[20:58:55] │     ├── three
+[20:58:55] │     └── <anonymous>
+```
+
+### `--tasks-simple`
+
+Command: `gulp --tasks-simple`
+
+Output: 
+```shell
+one
+two
+three
+four
+five
+```