1 |
|
2 |
|
3 |
|
4 |
|
5 |
|
6 |
|
7 |
|
8 |
|
9 |
|
10 | var path = require('path');
|
11 | var exec = require('./lib/exec');
|
12 |
|
13 |
|
14 |
|
15 |
|
16 |
|
17 |
|
18 |
|
19 | module.exports = function jsDocTask(grunt) {
|
20 | 'use strict';
|
21 |
|
22 | var errorCode = {
|
23 | generic: 1,
|
24 | task: 3
|
25 | };
|
26 |
|
27 | var jsdocFlags = ['access', 'configure', 'destination', 'debug', 'encoding', 'help', 'match', 'nocolor', 'private', 'package', 'pedantic', 'query', 'recurse', 'readme', 'template', 'test', 'tutorials', 'version', 'verbose', 'explain'];
|
28 |
|
29 |
|
30 |
|
31 | grunt.registerMultiTask('jsdoc', 'Generates source documentation using jsdoc', function registerJsdocTask() {
|
32 |
|
33 | var jsdoc,
|
34 | child;
|
35 | var params = {};
|
36 | var done = this.async();
|
37 | var options = this.options({
|
38 | 'ignoreWarnings': false,
|
39 | 'timeout': 60
|
40 | });
|
41 |
|
42 | var sources = this.filesSrc;
|
43 | var jsdocPath = this.data.jsdoc;
|
44 |
|
45 | if (!options.destination && this.files.length) {
|
46 |
|
47 | options.destination = this.files[0].dest || 'doc';
|
48 | }
|
49 |
|
50 |
|
51 | if (options.config) {
|
52 | params.configure = options.config;
|
53 | }
|
54 |
|
55 |
|
56 | jsdocFlags.forEach(function(flag) {
|
57 | if (typeof options[flag] !== 'undefined') {
|
58 | params[flag] = options[flag];
|
59 | }
|
60 | });
|
61 |
|
62 | if (jsdocPath && grunt.file.exists(jsdocPath) && grunt.file.isFile(jsdocPath)) {
|
63 |
|
64 | jsdoc = jsdocPath;
|
65 | } else {
|
66 |
|
67 | jsdoc = exec.lookup(grunt);
|
68 | }
|
69 |
|
70 |
|
71 | if (jsdoc === undefined) {
|
72 | grunt.log.error('Unable to locate jsdoc');
|
73 | grunt.fail.warn('Wrong installation/environnement', errorCode.generic);
|
74 | }
|
75 |
|
76 |
|
77 | jsdoc = path.relative('.', jsdoc);
|
78 |
|
79 | grunt.log.debug('Using jsdoc from : ' + jsdoc);
|
80 |
|
81 |
|
82 | if (sources.length === 0 && !params.configure) {
|
83 | grunt.log.error('No source files defined');
|
84 | grunt.fail.warn('Wrong configuration', errorCode.generic);
|
85 | }
|
86 |
|
87 |
|
88 |
|
89 | if (params.configure && !grunt.file.exists(params.configure)) {
|
90 | grunt.log.error('jsdoc config file path does not exist');
|
91 | grunt.fail.warn('Wrong configuration', errorCode.generic);
|
92 | }
|
93 |
|
94 | if (params.destination && !grunt.file.exists(params.destination) && !params.configure) {
|
95 | grunt.file.mkdir(options.destination);
|
96 | grunt.log.debug('create destination : ' + options.destination);
|
97 | if (!grunt.file.exists(params.destination)) {
|
98 | grunt.log.error('unable to create documentation folder : ' + params.destination);
|
99 | grunt.fail.warn('Wrong configuration', errorCode.generic);
|
100 | }
|
101 | }
|
102 |
|
103 |
|
104 | grunt.event.emit('generating.jsdoc', jsdoc, sources, params);
|
105 | child = exec.buildSpawned(grunt, jsdoc, sources, params);
|
106 |
|
107 | child.stdout.on('data', grunt.log.debug);
|
108 | child.stderr.on('data', function(data) {
|
109 | grunt.log.debug(data);
|
110 | if (!options.ignoreWarnings) {
|
111 | grunt.log.error(data);
|
112 | }
|
113 | });
|
114 | child.on('exit', function(code) {
|
115 | var resolvedDest;
|
116 | if (code === 0) {
|
117 | if(options.destination){
|
118 | resolvedDest = path.resolve(options.destination);
|
119 | grunt.log.ok('Documentation generated to ' + resolvedDest);
|
120 | } else {
|
121 | grunt.log.ok('Documentation generated');
|
122 | }
|
123 | grunt.event.emit('generated.jsdoc', resolvedDest);
|
124 |
|
125 | done(true);
|
126 | } else {
|
127 | grunt.fail.warn('jsdoc terminated with a non-zero exit code', errorCode.task);
|
128 | done();
|
129 | }
|
130 | });
|
131 | });
|
132 | };
|
133 |
|