165 lines
7.2 KiB
Markdown
165 lines
7.2 KiB
Markdown
|
# grunt-jsdoc [](https://travis-ci.org/krampstudio/grunt-jsdoc) [](http://badge.fury.io/js/grunt-jsdoc) [](http://gruntjs.com/)
|
||
|
|
|
||
|
|
[](https://nodei.co/npm/grunt-jsdoc.png?downloads=true&stars=true)
|
||
|
|
|
||
|
|
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][grunt] 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][getting_started] with:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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).
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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][getting_started].
|
||
|
|
|
||
|
|
First, add the `jsdoc` entry to the options of the `initConfig` method :
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
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](http://usejsdoc.org/about-including-readme.html).
|
||
|
|
* `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
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
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](https://github.com/terryweiss/docstrap), as well as the default template provided by jsdoc3. To use docstrap, you can use the following configuration:
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
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 :
|
||
|
|
|
||
|
|
```bash
|
||
|
|
$> grunt jsdoc
|
||
|
|
```
|
||
|
|
|
||
|
|
or integrate it to your build sequence :
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
grunt.registerTask('default', ['lint', 'test', 'jsdoc']);
|
||
|
|
```
|
||
|
|
|
||
|
|
## Contributing
|
||
|
|
|
||
|
|
Any contribution is welcome! Please check the [issues](https://github.com/krampstudio/grunt-jsdoc/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](https://github.com/krampstudio/grunt-jsdoc/issues/65))
|
||
|
|
* _0.5.1_ Update repo name to prevent confusion with previous version
|
||
|
|
* _0.5.2_ Upgrade to Grunt 0.4.3 (PR [#74](https://github.com/krampstudio/grunt-jsdoc/pull/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](https://github.com/krampstudio/grunt-jsdoc/issues/87)
|
||
|
|
* _0.5.7_ Update readme, docstrap version
|
||
|
|
* _0.4.0_ Update to jsdoc 3.2.0 stable, Fix [#37](https://github.com/krampstudio/grunt-jsdoc/issues/37), add integration tests
|
||
|
|
* _0.4.1_ Fix [#53](https://github.com/krampstudio/grunt-jsdoc/issues/53) and [#54](https://github.com/krampstudio/grunt-jsdoc/issues/54)
|
||
|
|
* _0.4.2_ Fix [#57](https://github.com/krampstudio/grunt-jsdoc/issues/57)
|
||
|
|
* _0.4.3_ Grunt 0.4.2 compliance, upgrade to jsdoc 3.2.2 and undeprecate the `dest` option ([#60](https://github.com/krampstudio/grunt-jsdoc/issues/60), [#63](https://github.com/krampstudio/grunt-jsdoc/issues/63) and [#66](https://github.com/krampstudio/grunt-jsdoc/issues/66))
|
||
|
|
* _0.3.0_ Partial rewrite, Fix [#29](https://github.com/krampstudio/grunt-jsdoc/pull/30) and minor typos fixs
|
||
|
|
* _0.3.1_ Fix [#29](https://github.com/krampstudio/grunt-jsdoc/issues/29)
|
||
|
|
* _0.3.2_ Fix [#32](https://github.com/krampstudio/grunt-jsdoc/issues/32)
|
||
|
|
* _0.3.3_ Fix [#34](https://github.com/krampstudio/grunt-jsdoc/issues/34) and [#36](https://github.com/krampstudio/grunt-jsdoc/issues/34)
|
||
|
|
* _0.2.0_ Migrate to grunt 0.4
|
||
|
|
* _0.2.1_ Fix [#10](https://github.com/krampstudio/grunt-jsdoc/issues/10)
|
||
|
|
* _0.2.2_ Fix [#11](https://github.com/krampstudio/grunt-jsdoc/issues/11)
|
||
|
|
* _0.2.3_ Fix [#14](https://github.com/krampstudio/grunt-jsdoc/pull/14) and [#15](https://github.com/krampstudio/grunt-jsdoc/issues/15)
|
||
|
|
* _0.2.4_ Fix Jsdoc 3 dependency to 3.1.1 tag, enables jsdoc options [#19](https://github.com/krampstudio/grunt-jsdoc/issues/19), enable to add jsdoc path [#13](https://github.com/krampstudio/grunt-jsdoc/issues/13) and add peerDependencies
|
||
|
|
* _0.1.0_ First release, includes basic support of [jsdoc3]
|
||
|
|
* _0.1.1_ Fix [#2](https://github.com/krampstudio/grunt-jsdoc/issues/2)
|
||
|
|
* _0.1.2_ Fix [#4](https://github.com/krampstudio/grunt-jsdoc/issues/4)
|
||
|
|
* _0.1.3_ Fix [#7](https://github.com/krampstudio/grunt-jsdoc/pull/7), Add [feature #8](https://github.com/krampstudio/grunt-jsdoc/pull/8)
|
||
|
|
* _0.1.4_ Use `child_process.spawn` instead of `exec` to run the command
|
||
|
|
|
||
|
|
|
||
|
|
[jsdoc3]: https://github.com/jsdoc3/jsdoc
|
||
|
|
|
||
|
|
## License
|
||
|
|
Copyright (c) 2012 Bertrand Chevrier
|
||
|
|
Licensed under the MIT license.
|
||
|
|
|
||
|
|
|
||
|
|
[grunt]: https://gruntjs.com
|
||
|
|
[node]: http://nodejs.org
|
||
|
|
[npm]: http://npmjs.org
|
||
|
|
[getting_started]: https://github.com/gruntjs/grunt/wiki/Getting-started
|
||
|
|
[usejsdoc]: http://usejsdoc.org
|
||
|
|
[usejsdocCli]: http://usejsdoc.org/about-commandline.html
|