Awesome
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 tooptions.destination
) set up the destination folder, the grunt wayjsdoc
: (optional) the path to the jsdoc bin (needed only for some border line cases)options
: options used by jsdocdestination
: 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
:warning: 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
)
:warning: 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.3.1 fix version of transitive dependency
- 2.2.0 jsdoc 3.5.0
- 2.2.1 fix version of transitive dependency
marked
to prevent xss
- 2.2.1 fix version of transitive dependency
- 2.1.0 use
cross-spawn
instead ofcross-spawn-async
, addgenerating
andgenerated
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.5.0 Move to NPM dependencies instead of git, jsdoc 3.2.2 (Fix #65)
- 0.4.0 Update to jsdoc 3.2.0 stable, Fix #37, add integration tests
- 0.3.0 Partial rewrite, Fix #29 and minor typos fixs
- 0.2.0 Migrate to grunt 0.4
- 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 ofexec
to run the command
License
Copyright (c) 2012 Bertrand Chevrier Licensed under the MIT license.