00mjk / grunt-jsdoc

A grunt plugin to generate javascript doc by running jsdoc3 on your grunt projects.

grunt-jsdoc

This plugin enables you to integrate the generation of comments based documentation into your Grunt build.

Generate your documentation

Install

This plugin requires Grunt >=0.4.0

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-jsdoc --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-jsdoc');

Configuration

First, add the jsdoc entry to the options of the initConfig method of your Gruntfile.js :

grunt.initConfig({
    jsdoc : {
        dist : {
            src: ['src/*.js', 'test/*.js'],
            options: {
                destination: 'doc'
            }
        }
    }
});

The supported options are

• src : an array of pattern that matches the files to extract the documentation from. You can also include a README.
• dest : (alias to options.destination) set up the destination folder, the grunt way
• jsdoc: (optional) the path to the jsdoc bin (needed only for some border line cases)
• options : options used by jsdoc
  • destination: the folder where the doc is generated
  • ... All jsdoc options are available (see usejsdocCli documentation).
  • ignoreWarnings : (optional) do not show jsdoc warnings

Code Documentation

This plugin is a wrapper around jsdoc3. Please refer to the documentation for the documentation details.

Templates

The plugin includes only the jsdoc3 template but you can configure any other jsdoc3 template. For example you can use ink-docstrap.

npm install --save-dev ink-docstrap

And in your Gruntfile.js :

jsdoc : {
    dist : {
        src: ['src/**/*.js', 'README.md'],
        options: {
            destination : 'doc',
               template : "node_modules/ink-docstrap/template",
              configure : "node_modules/ink-docstrap/template/jsdoc.conf.json"
        }
    }
}

Generation

To generate the documentation, you need to call the jsdoc task :

$> grunt jsdoc

or integrate it to your build sequence :

grunt.registerTask('default', ['lint', 'test', 'jsdoc']);

Compatibility

⚠️ Migrate from 0.x.x to 1.x.x branch :

I have removed the direct dependency to ink-docstrap. If you still want it, grab the dependency by yourself (npm install --save-dev ink-docstrap)

⚠️ Migrate from 1.x.x to 2.x.x branch :

The private option follows now the default jsdoc behavior : false by default.

Contributions

Every contribution is more than welcomed. You can:

• report issues
• Fix, improve the configuration, add new features. The best is to fork and submit a pull request
• Test and adapt to other OS
• Fix my English mistakes
• Update the documentation
• Create a better logo
• Offer me a coffee (I'm maintaining this plugin on my free time)

Upstream issues

For documentation related issues, please use the jsdoc issue tracker

To be sure the issue comes from the Grunt plugin, you can check by comparing the results with a jsdoc command. Run the task with the --debug flag to retrieve the jsdoc command to run.

Release History

• 2.4.0 jsdoc 3.6.0 (security update) and upgrade node support
  • 2.4.1 security update
• 2.3.0 jsdoc 3.5.5 and up to date dependencies
  • 2.3.1 fix version of transitive dependency marked to prevent regex dos
• 2.2.0 jsdoc 3.5.0
  • 2.2.1 fix version of transitive dependency marked to prevent xss
• 2.1.0 use cross-spawn instead of cross-spawn-async, add generating and generated grunt events
• 2.0.0 private behavior, cross-spawn-async instead of manual windows management
• 1.1.0 update to jsdoc 3.4.0 and make dest optional if a config file is set.
• 1.0.0 remove direct dependency to docstrap
• 0.6.0 jsdoc 3.0.0
  • 0.6.4 first stable using jsdoc 3.3.0
  • 0.6.5 code refactoring, docstrap 0.5.3, PR #120, better path management
  • 0.6.6 fix failing test
  • 0.6.7 Fix bug #136 and add more tests
  • 0.6.8 Fix bug #140, #143,
  • 0.6.9 Fix bug #144
  • 0.6.10 Revert wrong moving away docstrap dep
• 0.5.0 Move to NPM dependencies instead of git, jsdoc 3.2.2 (Fix #65)
  • 0.5.1 Update repo name to prevent confusion with previous version
  • 0.5.2 Upgrade to Grunt 0.4.3 (PR #74)
  • 0.5.3 Fix peer deps issue
  • 0.5.4 Fix peer deps issue
  • 0.5.5 Update docstrap version
  • 0.5.6 Fix dependencies version and bug #87
  • 0.5.7 Update readme, docstrap version
  • 0.5.8 Fix bug #116
• 0.4.0 Update to jsdoc 3.2.0 stable, Fix #37, add integration tests
  • 0.4.1 Fix #53 and #54
  • 0.4.2 Fix #57
  • 0.4.3 Grunt 0.4.2 compliance, upgrade to jsdoc 3.2.2 and undeprecate the dest option (#60, #63 and #66)
• 0.3.0 Partial rewrite, Fix #29 and minor typos fixs
  • 0.3.1 Fix #29
  • 0.3.2 Fix #32
  • 0.3.3 Fix #34 and #36
• 0.2.0 Migrate to grunt 0.4
  • 0.2.1 Fix #10
  • 0.2.2 Fix #11
  • 0.2.3 Fix #14 and #15
  • 0.2.4 Fix Jsdoc 3 dependency to 3.1.1 tag, enables jsdoc options #19, enable to add jsdoc path #13 and add peerDependencies
• 0.1.0 First release, includes basic support of [jsdoc3]
  • 0.1.1 Fix #2
  • 0.1.2 Fix #4
  • 0.1.3 Fix #7, Add feature #8
  • 0.1.4 Use child_process.spawn instead of exec to run the command

License

Copyright (c) 2012 Bertrand Chevrier Licensed under the MIT license.