gulp-jsdoc

jsDoc plugin adapter for gulp

Showing:

Popularity

Downloads/wk

845

GitHub Stars

56

Maintenance

Last Commit

6yrs ago

Contributors

5

Package

Dependencies

10

Size (min+gzip)

27.7KB

License

MIT

Type Definitions

Tree-Shakeable

No?

Categories

Deprecated!
This project is deprecated. Use gulp-jsdoc3 instead.

Readme

THIS PROJECT IS DEPRECATED

jsdoc has recently had a major rewrite to v3.4 (support for JSX, ES6). This plugin is no longer being maintained and is incompatible with this change. It is recommended you use gulp-jsdoc3 instead: https://github.com/mlucool/gulp-jsdoc3

npm uninstall --save-dev gulp-jsdoc
npm install --save-dev gulp-jsdoc3

Note: gulp-jsdoc3 is not backwards compatible with this project (gulp-jsdoc). You will have to make minor configuration changes.

gulp-jsdoc

NPM version Build Status Coverage Status Dependency Status Code Climate

jsdoc plugin for gulp

TL;DR

Install gulp-jsdoc as a development dependency:

npm install --save-dev gulp-jsdoc

Then, use it:

var jsdoc = require("gulp-jsdoc");

gulp.src("./src/*.js")
  .pipe(jsdoc('./documentation-output'))

API

jsdoc.parser(infos, name)

gulp.src("./src/*.js")
  .pipe(jsdoc.parser(infos, name))
  .pipe(gulp.dest('./somewhere'))

Will process any files it has been fed, and generate a new vinyl JSON usable by the generator to produce actual documentation.

By default, the filename is 'jsdoc.json' unless overriden by the name parameter.

Note that if you feed the parser a README.md file, this file will be rendered and used as a long description for your package.

eg:

gulp.src(["./src/*.js", "README.md"])
  .pipe(jsdoc.parser(infos, name))
  .pipe(gulp.dest('./somewhere'))

The optional infos parameter is fed to jsdoc.

infos.name

Type: String
Default: ''

infos.description

Type: String
Default: ''

infos.version

Type: String
Default: ''

infos.licenses

Type: Array
Default: []

infos.plugins

Type: Array
Default: false

jsDoc plugins to use. Example: ['plugins/markdown']

jsdoc.generator(destination, template, options)

gulp.src("./somewhere/jsdoc.json")
  .pipe(jsdoc.generator('./destination'))

or directly from the parser pipe:

gulp.src(["./src/*.js", "README.md"])
  .pipe(jsdoc.parser(infos, name))
  .pipe(jsdoc.generator('./destination'))

By default, the generator uses the default template.

destination

Type: String
Default: ''

Where the documentation will be outputed. If an infos object with a version / name was provided to the parser, these will be used in the final path.

template

You may optionnally specify a custom template, using the following syntax

{
  path: 'path_to_template',
  anyTemplateSpecificParameter: 'whatever'
}

As a courtesy, gulp-jsdoc bundles ink-docstrap templates, that you may use directly this way:

{
    path            : "ink-docstrap",
    systemName      : "Something",
    footer          : "Something",
    copyright       : "Something",
    navType         : "vertical",
    theme           : "journal",
    linenums        : true,
    collapseSymbols : false,
    inverseNav      : false
  }

See their site for more infos.

options

You may optionnally override default jsdoc behavior with this object:

  {
    showPrivate: false,
    monospaceLinks: false,
    cleverLinks: false,
    outputSourceFiles: true
  }

jsdoc(destination, template, infos, options)

gulp.src(["./src/*.js", "README.md"])
  .pipe(jsdoc('./destination'))

... is simply a shortcut for

gulp.src(["./src/*.js", "README.md"])
  .pipe(jsdoc.parser())
  .pipe(jsdoc.generator('./destination'))

Limitations

Only the parser is really using streams. While the generator will read from the result of the parser, it will also read and write templates files synchronously on its own.

There is nothing we can do about that, unless changing the jsdoc templating API entirely, and all existing templates...

Also, the following are currently not supported:

  • tutorials
  • sourcing configuration from jsdoc.conf files

If you have a use-case that you can't do with straight gulp in a better way, please say so.

License

MIT License

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100
No reviews found
Be the first to rate

Alternatives

No alternatives found

Tutorials

No tutorials found
Add a tutorial