Timothy J. Warren 6542c8f674 A bunch of random progress

2014-10-20 16:56:45 -04:00

7.2 KiB

Raw Blame History

grunt-jsdoc

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

NPM package name change

To comply with convention, the package's name was changed from grunt-contrib-jsdoc to grunt-jsdoc. You'll have to upgrade your package.json if you're still using grunt-contrib-jsdoc.

Install

You need grunt >= 0.4 as well as node and npm installed and running on your system.

You also need java installed and available in your PATH.

Install this grunt plugin next to your project's Gruntfile.js with:

npm install grunt-jsdoc --save-dev

jsdoc3 3.3.0

The jsdoc3 team is working on the 3.3.0 version that works on node.js and doesn't need Rhino (Java) anymore. This version is not yet stable (flagged as alpha). If you want this plugin to use this version, you can install the beta tag of this grunt plugin (branch 0.6.x).

npm install grunt-jsdoc@beta --save-dev

Feedback on the beta branch is more than welcomed!

Grunt <= 0.3.x

If you use the previous version of Grunt (0.3), you can install it with:

npm install grunt-jsdoc-plugin

Upstream issues

For documentation related issues, please ask the jsdoc3 people. To be sure the issue comes from the Grunt plugin, you can check by running directly jsdoc3 command. Run the task with the --debug flag and the command to run is outputed.

Documentation

Configuration

Configure the plugin to your project's Gruntfile.js.

First, add the jsdoc entry to the options of the initConfig method :

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

The supported options are

src : (required) an array of pattern that matches the files to extract the documentation from. You can also add the pattern to a README.md file to include it in your doc as described there.
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: (required) the folder where the doc is generated
- configure : (optional) path to a config file
- template : (optional) path or name to a different template
- private : (optional) include the private functions to the doc (true by default).
- ... refer the usejsdocCli documentation for all the available options.

Then, load the plugin

grunt.loadNpmTasks('grunt-jsdoc');

Code Documentation

The current version supports only jsdoc3 documentation style. The sources configured must contains valid jsdoc3 tags. Consult the usejsdoc website for the details.

Templates

The plugin includes docstrap, as well as the default template provided by jsdoc3. To use docstrap, you can use the following configuration:

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

Build

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']);

Contributing

Any contribution is welcome! Please check the issues. Do some unit/integration tests as far as possible.

Release History

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.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

7.2 KiB Raw Blame History