gulp-help-doc

gulp-help-doc

Self-documented gulp tasks with pretty printable usage information in command-line.

• Install
• Using
• How it works?
• Restrictions
• API
• License

Install

$ npm install gulp-help-doc

Using

Example gulpfile.js

var gulp = require('gulp');
var usage = require('gulp-help-doc');
var args = require('yargs').argv;

/**
 * This simply defines help task which would produce usage
 * display for this gulpfile. Simple run `gulp help` to see how it works.
 * NOTE: this task will not appear in a usage output as far as it is not
 * marked with the @task tag.
 */
gulp.task('help', function() { return usage(gulp); });


/**
 * We may also link usage as default gulp task:
 */
gulp.task('default', ['help']);


/**
 * This task will appear in usage output, because it is marked with the
 * proper @task tag. Current information you're reading will be the task
 * description.
 *
 * @task {demo}
 * @order {1}
 */
 gulp.task('demo', function() {});

/**
 * Another task, which could handle some command-line argulents, for example,
 * by using 'yargs' module. It is possible to describe expected by a task
 * arguments using @arg tags. It is possible to specify as much argument
 * tags as required by the job done within this task. For example here we 
 * describe three arguments:
 *
 * @task {test}
 * @arg {argOne} first argument description which will appear in usage output
 * @arg {argTwo} second argument dsescription
 * @arg {argThree} third argument description
 */
gulp.task('test', ['demo'], function() {
    var one = args.argOne;
    var thwo = args.argTwo;
    var three = args.argThree;

    // ... do something taking args into account ...

});

Put this example gulpfile in your project's root directory and run the following commands to install dependencies:

$ npm install yargs gulp gulp-help-doc

Now you can simply run

$ gulp help

or even more simply

$ gulp

and it will print you the proper usage information. It should look like:

Usage: gulp [task] [options]
Tasks:
    demo            This task will appear in usage output, because it is marked with 
                    the proper @task tag. Current information you're reading will 
                    be the task description.

    test            Another task, which could handle some command-line argulents, 
                    for example, by using 'yargs' module. It is possible to describe 
                    expected by a task arguments using @arg tags. It is possible 
                    to specify as much argument tags as required by the job done 
                    within this task. For example here we describe three arguments:
     --argOne       first argument description which will appear in usage output
     --argTwo       second argument dsescription
     --argThree     third argument description
                    Depends: ["demo"]

How it works?

This plugin enables you to use jsDoc-like tags to document your tasks and make those task documentation availabe from command-line as usage information.

• @task {task_name}
• @arg {arg_name} arg_description

Task description could be written in a free form before the @task tag declaration.

If @task tag is omitted then the task will not appear in usage call.

Optionally, you can use the @order tag to sort the tasks descriptions in the output. A task with @order {1} will appear before a task with @order {2}. All tasks without this tag will appear at the end of the list, sorted alphabetically.

Restrictions

When using TypeScript version of gulpfile it does not support task doc definitions outside of main gulpfile.ts, so it is recommended to describe with docs all tasks in a main gulpfile.

API

This module provides you with usage() function which takes 2 arguments:

• gulp - the instance of gulp, usage info for which must be printed
• options - optional parameter, which allows to tune some printing options.

Options are:

• lineWidth - max line width for the printed output lines (by default is 80 characters long)
• keysColumnWidth - max width of the column width tasks/args names (by default is 20 characters long)
• padding - number of empty characters for left-padding of the output
• logger - printing engine (by default is console). May be changed to gulp-util or some other printing device if required.
• displayDependencies - if set to true (default), prints the task dependencies below its help description
• emptyLineBetweenTasks - if set to true (default), prints an empty line between tasks help descriptions

Example of custom configuration:

const usage = require('gulp-help-doc');
const gutil = require('gulp-util');

gulp.task('help', function() {
    return usage(gulp, {
        lineWidth: 120,
        keysColumnWidth: 30,
        logger: gutil
    });
});

License

MIT