deshaw / gulp-jsdoc3 Goto Github PK

npm WARN deprecated [email protected]: wrench.js is deprecated! You should check out fs-extra (https://github.com/jprichardson/node-fs-extra) for any operations you were using wrench for. Thanks for all the usage over the years.

Please update/change your code to use fs-extra as suggested. 😄

Error: JSDoc closed with error code: 1
at ChildProcess. (node_modules\gulp-jsdoc3\dist\gulp-jsdoc.js:145:32)
at emitTwo (events.js:87:13)
at ChildProcess.emit (events.js:172:7)
at maybeClose (internal/child_process.js:821:16)
at Process.ChildProcess._handle.onexit (internal/child_process.js:211:5)

I wanted to use this package in my gulp pipeline, unfortunately it doesn't appear to work with gulp 4.

Steps to reproduce:
download this repository, in package.json change the gulp dependency to the following:
"gulp": "gulpjs/gulp#v4.0.0"

run ./node_modules/.bin/gulp

and get the following error:

AssertionError [ERR_ASSERTION]: Task function must be specified
    at Gulp.set [as _setTask] (/Users/keneucker/Downloads/gulp-jsdoc3-master/node_modules/undertaker/lib/set-task.js:10:3)
    at Gulp.task (/Users/keneucker/Downloads/gulp-jsdoc3-master/node_modules/undertaker/lib/task.js:13:8)
    at Object.<anonymous> (/Users/keneucker/Downloads/gulp-jsdoc3-master/gulpfile.js:63:6)

I notice that the output generated files are not completely written on disk while the task is considered as done.
Then if we want to post-process a generated file, the file does not yet exists on disk.

For example, in the following case, the second task will fail since the output index.html file does not exist while the first task is completed.
Also, the debug trace 'Documented N files!' will appear after both tasks are completed.

gulp.task('generateDoc', function() {
    return gulp.src([<source_files>], {read: true})
        .pipe(jsdoc(config))
        .on('end', function() {
            console.log("DONE!!!!!!!!");
    });
});

gulp.task('doc', ['generateDoc'], function() {
    return gulp.src([<ouput_dir>/'index.html'], {base: './'})
        .pipe(htmlReplace({...})
        .pipe(gulp.dest('./'));
});

Used versions:

• node: 4.2.6
• jsdoc: 3.4.3
• gulp-jsdoc3: 1.0.1

If not, I would like to submit a PR with this bundle eliminated.

In case of generating docs by jsdoc and publish on github, Im receiving the warning about "security vulnerability: jQuery" which is kept in prettify.

my task

import jsdocConfig from './jsdoc';

export function docs_scripts(cb) {
    gulp.src(['jsdoc.md','./src/scripts/*.js'], {read: false})
        .pipe($.jsdoc3(config, cb));
}

and get this ▼
There are no input files to process.

If jsdoc() with an single argument only this may be either a congig object or a done callback. Unfortunately, the handling of optional parameters is wrong. If jsdoc is called with an config object it will be treated as an done callback internally.

The task fails on gulp 4.0 alpha 2

[11:17:55] Starting 'jsDoc'...
[11:17:55] Starting 'jsdoc_generation'...
[11:17:56] fs.js:584
  return binding.open(pathModule._makeLong(path), stringToFlags(flags), mode);
                 ^

Error: ENOENT: no such file or directory, open 'C:\prog\ziperrom1.github.io\awesomechatroom-doc\jsDoc\lib_navigation%0A%0AHandle%20the%20current%20page%20attributes%20such%20as%20the%20page%20title%20or%20the%20page%20parameters.%0AIt%20loads%20pages%20by%20hide%20_%20show%20pages%20DOM%20classes%20elements%20to%20use%20a%20Single%20Page%20Web%20pattern%20and%20avoiding%20browser%0Apage%20reloading%20to%20keep%20the%20WebSocket%20connection%20alive.%0AIt%20load%20pages%20on%20hashchange%20event%20and%20detect%20the%20page%20to%20load%20by%20parsing%20the%20hash.module_.html'
    at Error (native)
    at Object.fs.openSync (fs.js:584:18)
    at Object.fs.writeFileSync (fs.js:1224:33)
    at generate (C:\prog\awesomechatroom\static\node_modules\ink-docstrap\template\publish.js:262:6)
    at Object.exports.publish (C:\prog\awesomechatroom\static\node_modules\ink-docstrap\template\publish.js:783:9)
    at Object.module.exports.cli.generateDocs (C:\prog\awesomechatroom\static\node_modules\jsdoc\cli.js:430:39)
    at Object.module.exports.cli.processParseResults (C:\prog\awesomechatroom\static\node_modules\jsdoc\cli.js:383:20)
    at module.exports.cli.main (C:\prog\awesomechatroom\static\node_modules\jsdoc\cli.js:227:14)
    at Object.module.exports.cli.runCommand (C:\prog\awesomechatroom\static\node_modules\jsdoc\cli.js:180:5)
    at C:\prog\awesomechatroom\static\node_modules\jsdoc\jsdoc.js:103:9
    at Object.<anonymous> (C:\prog\awesomechatroom\static\node_modules\jsdoc\jsdoc.js:104:3)
    at Module._compile (module.js:413:34)
    at Object.Module._extensions..js (module.js:422:10)
    at Module.load (module.js:357:32)
    at Function.Module._load (module.js:314:12)
    at Function.Module.runMain (module.js:447:10)

[11:17:56] JSDoc returned with error code: 1
[11:17:56] 'jsdoc_generation' errored after 1.38 s

Hello,

The current version of jsdoc include in this package is 3.4.1 but it is broken under node v12.

To fix this you need to update jsdoc to v3.6.0.

Here a topic about this issue: Node.js 12 support

Best regards.

Hi
I want to build a big project. I run into this issue. Thank you.

Windows 10
Nodejs 4
npm 3.8.0

[13:59:07] Starting 'doc'...
internal/child_process.js:298
    throw errnoException(err, 'spawn');
    ^

Error: spawn ENAMETOOLONG
    at exports._errnoException (util.js:874:11)
    at ChildProcess.spawn (internal/child_process.js:298:11)
    at exports.spawn (child_process.js:339:9)
    at D:\me\CodeRepository\webapp\node_modules\gulp-jsdoc3\dist\gulp-jsdoc.js:112:51
    at D:\me\CodeRepository\webapp\node_modules\karma\node_modules\graceful-fs\graceful-fs.js:43:10
    at FSReqWrap.oncomplete (fs.js:82:15)

Is it possible for user to override the default docstrap configuration?

I'd like to use a different them than Cerulean.

Do you know what the best way to rename the output file is?

Starting 'document-output'...
[17:26:55] Finished 'document-output' after 59 ms
internal/child_process.js:298
throw errnoException(err, 'spawn');
^

Error: spawn EACCES
at exports._errnoException (util.js:870:11)
at ChildProcess.spawn (internal/child_process.js:298:11)
at exports.spawn (child_process.js:362:9)
at /home/project/node_modules/gulp-jsdoc3/dist/gulp-jsdoc.js:112:121
at /home/project/node_modules/graceful-fs/graceful-fs.js:104:5
at FSReqWrap.oncomplete (fs.js:82:15)

On our project, we do have several md files that explains different parts of the app.

Would be possible to add this feature or it is there already ?

If we pass a glob pointing to our md folder (where all of our md files are), gulp-jsdoc only uses the last one there.

Thanks !

After jsdoc update 3.4.2 -> 3.5.0 the following error comes out to console

Cannot use config file C:\Users\...\AppData\Local\Temp\tmp-74120Pc6ecFXqFbwS.tmp.
Only .js and .json files are supported.

Sorry, my English is not very good.
I met a problem, I want to use in single file vue jsdoc, and configure automatic monitoring (jsdoc-vue) generated document, but not make, through the detection is the jsdoc configuration of includePattern don't (can't listen vue file), do not use the gulp with global jsdoc directly through the configuration file can listen to, can how to solve

I have the following jsdoc.conf.json file:

{
  "opts": {
    "destination": "doc"
  },
  "tags": {
    "allowUnknownTags": true
  },
  "plugins": ["plugins/markdown"],
  "markdown": {
    "parser": "gfm",
    "hardwrap": true
  }
}

and gulp task:

var gulp = require('gulp'),
  jsdoc = require('gulp-jsdoc3'),
  config = require('../config/jsdoc.conf.json');

gulp.task('jsdoc', function() {
  return gulp.src('app/**/*.js')
    .pipe(jsdoc(config));
});

gulp.task('doc:js', ['jsdoc']);
gulp.task('doc', ['doc:js']);

After the task is done running, jsdoc files are placed under docs/ folder, which looks like the default one.

Am I doing anything wrong?

I'm trying to change the theme used for the generated docs, but without much success.

I've installed another theme using npm (jsdoc-oblivion), and change the path and theme properties, but with no effect.

I set this up as per your instructions and when I run it says that it has "Documented 13 files!", but no actual folder is created with the documentation. I have setup the config file as follows:

{
    "tags": {
        "allowUnknownTags": true,
        "dictionaries": ["jsdoc","closure"]
    },
    "source": {
        "includePattern": ".+\\.js(doc)?$",
        "excludePattern": "(^|\\/|\\\\)_"
    },
    "opts": {
        "destination": "./docs/"
    },
    "plugins": [],
    "templates": {
        "cleverLinks": false,
        "monospaceLinks": false
    }
}

My gulp file is this:

var gulp          = require('gulp');
var jsdoc         = require('gulp-jsdoc3');
var config        = require('../config');
var jsdocConfig   = require('../../jsdocConfig');

gulp.task('docs', function (cb) {
    gulp.src('./app/src/modules/**/*.js', {read: false})
        .pipe(jsdoc(jsdocConfig, cb));
});

This is my .jsdoc.json

{
"tags": {
"allowUnknownTags": true,
"dictionaries": ["jsdoc", "closure"]
},
"opts": {
"template":"minami",
"encoding": "utf-8",
"destination": "./docs/",
"recurse": true
},
"templates":{
"path":"minami"
}
}

Why does it not resolve minami as the template?
It also does not work with values including
./node_modules/minami
when i set the layoutFile in templates.default to minami/tmpl/layout.tmpl it also does not work

Hi,

Sorry to ask something about angularJS but i don't found documentation about this. If i use @ngDocs controller , that seems doesn't work :/

i'm a little bit confused between ngdocs , jsdocs etc

Thank you :)

This is a part of the log from travis-ci:

Unhandled rejection AssertionError: expected [Error: ENOENT: no such file or directory, open '/tmp/tmp-2733MA0IclnLiPOp/testFile.js.html'] to not exist
    at gulp-jsdoc_spec.js:118:21
    at bound (domain.js:287:14)
    at runBound (domain.js:300:12)
    at tryCatcher (/home/travis/build/mlucool/gulp-jsdoc3/node_modules/bluebird/js/release/util.js:16:23)
    at Promise._settlePromiseFromHandler (/home/travis/build/mlucool/gulp-jsdoc3/node_modules/bluebird/js/release/promise.js:503:31)
    at Promise._settlePromise (/home/travis/build/mlucool/gulp-jsdoc3/node_modules/bluebird/js/release/promise.js:560:18)
    at Promise._settlePromise0 (/home/travis/build/mlucool/gulp-jsdoc3/node_modules/bluebird/js/release/promise.js:605:10)
    at Promise._settlePromises (/home/travis/build/mlucool/gulp-jsdoc3/node_modules/bluebird/js/release/promise.js:680:18)
    at Async._drainQueue (/home/travis/build/mlucool/gulp-jsdoc3/node_modules/bluebird/js/release/async.js:126:16)
    at Async._drainQueues (/home/travis/build/mlucool/gulp-jsdoc3/node_modules/bluebird/js/release/async.js:136:10)
    at Immediate.Async.drainQueues [as _onImmediate] (/home/travis/build/mlucool/gulp-jsdoc3/node_modules/bluebird/js/release/async.js:16:14)
    at processImmediate [as _immediateCallback] (timers.js:383:17)

I ran this a few times in a few different environments (both before/after fixing #17), and it seems that jsdoc during this test does not create 'testFile.js.html'. I believe this is because there is no layout template for individual source files. For some reason, the failure of this assertion does not stop deployment on travis (or even get caught by istanbul).

Is the file supposed to be generated? Or perhaps it wouldn't be generated under this layout?

It is difficult to fix #17 with an incorrect test (a stream is being treated like a promise).

EDIT: I removed the log as it pertained towards a different test.

The handling of the stream is incorrect on lines 105-123.

hello, when I run "npm install" , i have this issue :

npm ERR! node v4.2.4
npm ERR! npm v3.8.5

npm ERR! No compatible version found: gulp-jsdoc3@~3.4.0
npm ERR! Valid install targets:
npm ERR! 0.2.1, 0.2.0, 0.1.1, 0.1.0, 0.0.3, 0.0.2, 0.0.1

Hi @mlucool,

thanks for picking up this project.

When running npm install gulp-jsdoc3 and trying to include it in my gulp file I get an error saying Cannot find module 'gulp-jsdoc3'.

I looked inside node_modules/gulp-jsdoc3 and it seems the index.js is missing…

Any ideas?

Thanks
Felix

Gulp doc task returns an error while executing this test code :

var jsdoc = require('gulp-jsdoc3');
gulp.task('doc', function (cb) {
  gulp.src('source/js/**/*.js', {read: false})
      .pipe(jsdoc(cb));
});

Cannot parse the config file /tmp/tmp-7055paabrxtXIJt8.tmp: SyntaxError: Unexpected token u

But I can't see the temporary file content because it is automatically removed.

npm package is not in sync with latest master commit. Pls update package.json to 1.0.1, and execute:

npm login
npm publish

I am trying to build the jsdoc3 into my gulp process by not only building the documents on default but I want them to update as a developer is coding so they can see if the content is outputting correctly via browsersync.

The issue is that every time the code changes the jsdocs gets rewritten via a watch as a duplicate instead of a fresh document. Each time the watch runs the exact content gets duplicated over and over again for as many times as the code has changed.

The first time the jsdocs is called everything works fine it is only when you call the task via a watch. Here is my gulp to provide some context.

Is there a way to clear, flush or something else to make this more of a living document versus a one time build?

gulp.task('doc', function (cb) {
    gulp.src(['README.md', './src/js/**/*.es6.js'], {read: true})
        .pipe(jsdoc(jsdocConfig,cb));   
});
gulp.task('dev', function () {
    devCompiler.run(function (err, stats) {
        if (err) throw new gutil.PluginError('webpack:dev', err);
        reload();
    });
});
gulp.task('env', function () {
    browserSync({
        notify: true,
        port: 9000,
         ui: {
            port: 3000
        },
        server: {
            baseDir: ['./dist']
        }
    });

    var docs = browserSync.create()
    docs.init({
        notify: true,
        port: 9090,
        ui: {
            port: 9090
        },
        server: {
            baseDir: ['./docs']
        }
    });
    gulp.watch('./src/js/**/*.es6.js', ['lint','dev','doc']);
});

gulp.task('default', ['dev', 'doc', 'env']);

It is not work with jaguarjs-jsdoc.
src/jsdocConfig.json

{
  "tags": {
    "allowUnknownTags": true
  },
  "source": {
    "excludePattern": "(^|\\/|\\\\)_"
  },
  "opts": {
    "destination": "./docs/gen"
  },
  "plugins": [
    "plugins/markdown"
  ],
  "templates": {
    "cleverLinks": false,
    "monospaceLinks": false,
    "default": {
      "outputSourceFiles": true
    },
    "path": "ink-docstrap", // here, i changed to jaguarjs-jsdoc, but it don't work .
    "theme": "cerulean",
    "navType": "vertical",
    "linenums": true,
    "dateFormat": "MMMM Do YYYY, h:mm:ss a"
  }
}

i can not find any code to process templates.path, but in file 'gulp-jsdoc3/dist/gulp-jsdoc.js', i find this:

 // Config + ink-docstrap if user did not specify their own layout
   if (!jsdocConfig.templates || !jsdocConfig.templates.default || !jsdocConfig.templates.default.layoutFile) {
        args = args.concat(['-t', inkdocstrap]);
   }

When running gulp-jsdoc3 I'm getting the following error: ERROR: The @license tag requires a value. File: lunr.min.js, line: 1. I see that the license field is indeed blank but can't find the source of the file being copied to the output directory to make a pull request.

This appears to be an issue in the lunr repository but I'm not sure if it's gulp's handling of JSdoc or somehting else.

I've filed olivernn/lunr.js#217 against the lunr repository for them to fix the issue upstream

Until this is fixed, where do I pull the source for lunr so I can manually remove the tag?

Seems as if the completion callback is called once per file. Omitting it seems to have fixed it for me, incoming PR with doc changes, up to you! Thanks

I installed the latest version of gulp-jsdoc3 (v1.0.1), and documentation assets do not seem to be generated correctly. Each generated asset is being put in its own directory, named the same filename. For example, my index.html file is trying to read /styles/sunlight.default.css but cannot find it because it's not in the /styles/ folder: it's located at /styles/sunlight.default.css/sunlight.defualt.css. This seems to be an issue with mkdirp usage. Screenshot of generated files attached.

On January 9th, eed146d was pushed to this repository.

In that commit gulp was moved from a devDependency to a peerDependency. The behavior of npm version 2 is to install peer dependencies. So a project using gulp, along with this plugin, will get gulp 3.9.0 or higher (but major version 3).

Recently I started using gulp version 4 (It's still in beta as a 4 branch on the gulp repo).

That requires that I list gulp 4 as a devDependency of my project. I also use this plugin in my project. This causes a version conflict between my project's gulp version, and the peerDependency of this project. Inevitably the gulp version required by this project gets installed causing my project's build to fail.

As this project has no strict dependency on gulp, other than that this plugin is used in a stream, could the peerDependency requirement be either removed, or relaxed to include gulp version 4.

On a side note, this project works great with version 4 (Worked well until the aforementioned changed)

Gulp File/Task:

gulp.task('generate-jsdoc', function(cb) {
    var config = require('./src/main/resources/template/conf.json');
    gulp.src([ './src/main/resources/*.js' ], {
        read : false
    }).pipe($.jsdoc3(config, cb));
});

Error Messages;
FATAL: Unable to load template: Cannot find module '/usr/lib/node_modules/docdash/publish'

File System:

node_modules
    +docdash
        +publish.js

I use gulp-jsdoc3 with gulp-watch to develop jsdoc-template.

When a file changes, the jsdoc creates redundant documents.
(No create files)

It is a bug?

gulpfile.js

'use strict';
var path = require('path');
var gulp = require('gulp');
var browserify = require('browserify');
var del = require('del');
var connect = require('gulp-connect');
var jsdoc = require('gulp-jsdoc3');
var uglify = require('gulp-uglify');
var concat = require('gulp-concat');
var source = require('vinyl-source-stream');
var buffer = require('vinyl-buffer');

/* Demo paths */
var DEMO_PATH = path.join(__dirname, 'demo');
var DEMO_TEMPLATE_PATH = __dirname;
var DEMO_DESTINATION_PATH = path.join(DEMO_PATH, 'doc');

var demoFilePaths = ['README.md', 'src/**/*.js'].map(function (filePath) {
    return path.join(DEMO_PATH, filePath);
});

/**
 * Generate demo document
 */
gulp.task('demo', ['del'], function(done) {
    /* Demo config */
    var config = require(path.join(DEMO_PATH, 'jsdoc-conf.json'));
    config.opts.template = DEMO_TEMPLATE_PATH;
    config.opts.destination = DEMO_DESTINATION_PATH;

    gulp.src(demoFilePaths, {read: false})
        .pipe(jsdoc(config, done));
});

/**
 * Watch file paths
 * @type {string[]}
 */
var watchPaths = [
    'demo/src/**/*.js',
    'demo/jsdoc-conf.json',
    'demo/samples/**/*',
    'static/script/**/*.js',
    'static/styles/**/*.css',
    'tmpl/**/*.tmpl',
    'publish.js'
];

/**
 * Reload server
 */
gulp.task('reload', ['demo'], function() {
    return gulp.src(watchPaths)
        .pipe(connect.reload())
});

/**
 * Regenerate demo document when a file changes
 */
gulp.task('watch', ['demo'] ,function() {
    var watcher = gulp.watch(watchPaths, ['demo', 'reload']);

    watcher.on('change', function (event) {
        console.log('File: ' + event.path + ' was ' + event.type + ', running tasks...');
    });
});

/**
 * Run web server
 */
gulp.task('connect', ['demo'], function() {
    connect.server({
        root: 'demo/doc',
        livereload: true
    });
});

/**
 * @command gulp serve
 * Connect-server with watch
 */
gulp.task('serve', ['connect', 'watch']);


/**
 * @command gulp del
 * Delete all demo-doc files
 */
gulp.task('del', function() {
    return del([DEMO_DESTINATION_PATH]);
});

Hello,

I'm trying to produce documentation, this is the script I'm using:

let gulp = require('gulp');
const jsdoc = require('gulp-jsdoc3');

gulp.task('doc', function(cb) {
    const config = require('./jsdoc.json');
    gulp.src(['README.md', './source/js/classes/**/*.js', "./source/js/libs/**/*.js", "./source/js/router.js", "./source/js/utils.js", "./source/js/generic.js"], { read: false })
        .pipe(jsdoc(config, cb));
});

My files use es6 with import and class if it helps. But none of the files get produced, the folder and index.html and quicksearch.html do get produced however.

The console logs this:

Using gulpfile C:\xampp\htdocs\myproject\gulpfile.js
Starting 'doc'...
Documented 21 files!
Finished 'doc' after 1.98 s

And my jsdoc is this:

{
    "tags": {
        "allowUnknownTags": true
    },
    "opts": {
        "destination": "./docs/gen"
    },
    "plugins": [
        "plugins/markdown"
    ],
    "templates": {
        "cleverLinks": false,
        "monospaceLinks": false,
        "default": {
            "outputSourceFiles": true
        },
        "path": "ink-docstrap",
        "theme": "Cosmo",
        "navType": "vertical",
        "linenums": true,
        "dateFormat": "MMMM Do YYYY, h:mm:ss a"
    }
}

Any ideas what is going on?

The module tries to load jsdoc inside the gulp-jsdoc3 folder. In npm 3 the dependencies are installed in a flat structure and this causes an error.

In the docs I see this:

{
    "templates": {
        "default": {
            // Set my own layout file
            "layoutFile": "./layout.tmpl"
        }
    }
}

But where is that in relation to what?

I've placed the "layout.tmpl" file at the same level (in the same directory) as the "jsdoc.json" file (the config file itself), made a few changes ... but nothing has changed. What am I missing?

Due to a »complex« system I load libraries from elsewhere besides node_modules.

I reference the DOM from modules with $ (jQuery) without any issues.

But gulp-jsdoc3 doesn't seem to like this, it throws errors:
ReferenceError: $ is not defined

How can I suppres gulp-jsdoc3 from doing this?