Skip to content

deshaw/gulp-jsdoc3

This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Folders and files

NameName
Last commit message
Last commit date

Latest commit

60ed46c · Jan 14, 2018

History

39 Commits
Jan 14, 2018
Oct 22, 2016
Oct 24, 2016
Dec 19, 2015
Dec 19, 2015
May 28, 2016
Nov 4, 2016
Dec 10, 2015
Oct 7, 2016
Feb 2, 2016
Dec 19, 2015
Jan 14, 2018
Jan 14, 2018

Repository files navigation

gulp-jsdoc3

NPM version NPM DM Build Status Coverage Status Dependency Status

jsdoc plugin for gulp

Installation

Install gulp-jsdoc as a development dependency:

npm install --save-dev gulp-jsdoc3

Usage

var jsdoc = require('gulp-jsdoc3');

gulp.task('doc', function (cb) {
    gulp.src(['README.md', './src/**/*.js'], {read: false})
        .pipe(jsdoc(cb));
});

By default, documentation is output to docs/gen. gulp-jsdoc3 does not modify the source vinyl stream so the output location can only be specified via config, not gulp.dest(). You can see all the default options passed to jsdoc in src/jsdocConfig.json.

You can also pass in your own config to override the defaults. All CLI options can be specified here.

var jsdoc = require('gulp-jsdoc3');

gulp.task('doc', function (cb) {
    var config = require('./jsdoc.json');
    gulp.src(['README.md', './src/**/*.js'], {read: false})
        .pipe(jsdoc(config, cb));
});

Another good example is in this project's gulpfile!

Overriding the default layout

ink-docstrap is used as the default layout but you can easily override it in your config like this:

{
    "templates": {
        "default": {
            // Set my own layout file
            "layoutFile": "./layout.tmpl"
        }
    }
}

Other config tips and tricks

Use include and exclude patterns to filter the globs from gulp even more. For example, only include .js,.jsdoc, or .jsx files that do not start with _:

"source": {
    "includePattern": ".+\\.js(doc|x)?$",
    "excludePattern": "(^|\\/|\\\\)_"
}

If you want to document multiple markdown or html files, enable tutorial support:

"tutorials": "path/to/tutorials"

Debugging

Set env variable: DEBUG=gulp-jsdoc3

Notes

This is a reasonable attempt to wrap jsdoc using gulp as thinly as possible use the jsdoc config to pass in files from gulp. jsdoc does not allow for piped input, so this attempt may be considered a gulp anti-pattern. It also does not pass on output to be piped elsewhere.

I would like to thank Mangled Deutz @ gulp-jsdoc for the original implementation.

License

Apache-2.0 License