nanopx / gulp-esdoc Goto Github PK

Gulp plugin for ESDoc

JavaScript 100.00%

gulp-esdoc's Introduction

gulp-esdoc

Gulp plugin for ESDoc

Installation

npm install gulp-esdoc --save-dev

Usage

var esdoc = require("gulp-esdoc");

// document "./src" folder and output at "./docs" folder
gulp.src("./src")
  .pipe(esdoc({ destination: "./docs" }));

API

esdoc(options)

options.destination is required. See here for more options.

Tests

Run:

npm test

License

MIT

gulp-esdoc's People

Contributors

Stargazers

Watchers

Forkers

virtyaluk arcticshadow armature-corp floydpink lokidokicoki mr-ssk marcominetti lwgojustgo icambron fkm jaceyshome

gulp-esdoc's Issues

IceCap Unexpected strict mode reserved word with gulp-esdoc 0.2.0 + es-doc 0.4.7

I'm getting the following error on my gulp build when installed from fresh:

/frontend/node_modules/gulp-esdoc/node_modules/esdoc/node_modules/ice-cap/out/src/IceCap.js:18
let logger = new _colorLogger2.default('IceCap');
^^^
SyntaxError: Unexpected strict mode reserved word
    at exports.runInThisContext (vm.js:73:16)

I'm I find the line: frontend/node_modules/gulp-esdoc/package json

"esdoc": "^0.4.3",

and change it to be:

"esdoc": "0.4.3",

then reinstall gulp-esdoc, it fixes the issue for me. Might be worth something looking into?

please support config file.

the .esdocrc file can use in esdoc module. I didn't find a way to use config-file way in gulp-esdoc.

IceCap missing dependency?

var logger = new Logger("IceCap");
^

TypeError: Logger is not a function

Please update to ESDoc 1.0.1

There are some breaking changes, though - https://esdoc.org/manual/CHANGELOG.html

I can only see my README.md contents

Hello,

I tried using gulp-esdoc today but the only thing I managed to do is get my README.md file working.

Here is my gulp task:

gulp.task('documentation', function () {
gulp.src("./client/")
.pipe(esdoc({
destination: "./docs",
index : "./README.md"
}));
});

For now I only have a single js file in ./client/, it is main.js:

/**

this is MyClass description.
@example
let myClass = new MyClass();
/
class MyClass {
/*
- this is constructor description.
- @param {number} arg1 this is arg1 description.
- @param {string[]} arg2 this is arg2 description.
  */
  constructor(arg1, arg2) {
}
}

I used this just to test the task. But when I open the index.html from the ./docs folder, I only see the README and the raw source code of main.js. Why can't I see the documentation generated for MyClass ?

Thanks,

RangeError: Maximum call stack size exceeded

I'm getting a RangeError for whatever reason using gulp-esdoc.

/home/nulldivision/MyProject/node_modules/esdoc/out/src/Publisher/Builder/DocResolver.js:95
            throw _iteratorError;
            ^

RangeError: Maximum call stack size exceeded
    at module.exports (/home/nulldivision/MyProject/node_modules/babel-polyfill/node_modules/core-js/modules/_an-object.js:2:26)
    at RegExp.toString (/home/nulldivision/MyProject/node_modules/babel-polyfill/node_modules/core-js/modules/es6.regexp.to-string.js:16:13)
    at String (native)
    at RegExp.<anonymous> (/home/nulldivision/MyProject/node_modules/esdoc/node_modules/core-js/modules/$.replacer.js:7:12)
    at RegExp.toString (/home/nulldivision/MyProject/node_modules/babel-polyfill/node_modules/core-js/modules/es6.regexp.to-string.js:18:23)
    at String (native)
    at RegExp.<anonymous> (/home/nulldivision/MyProject/node_modules/esdoc/node_modules/core-js/modules/$.replacer.js:7:12)
    at RegExp.toString (/home/nulldivision/MyProject/node_modules/babel-polyfill/node_modules/core-js/modules/es6.regexp.to-string.js:18:23)
    at String (native)
    at RegExp.<anonymous> (/home/nulldivision/MyProject/node_modules/esdoc/node_modules/core-js/modules/$.replacer.js:7:12)

Config:

{
  "source": "./",
  "destination": "esdoc/dist/api-doc/src",
  "includes": [
    "\\.js$"
  ],
  "excludes": [
    "gulpfile.babel.js",
    "coverage",
    "dist",
    "node_modules",
    "test"
  ],
  "plugins": [
    {
      "name": "esdoc-importpath-plugin",
      "option": {
        "replaces": [
          {
            "from": "\\.js$",
            "to": ""
          }
        ]
      }
    }
  ],
  "styles": [
    "./esdoc/esdoc.css"
  ],
  "title": "MyProject"
}

This doesn't happen with CLI eslint.

Seems like gulp-esdoc doesn't pick up esdoc configuration file.

I've noticed that gulp-esdoc throws an error if esdoc passed to pipeline with no arguments. Original esdoc works well with config file placed in the root of the project. So, I think, it would be nice if gulp-esdoc had an opportunity to use this config file as well.

ESDoc.generate

gulpfile:

gulp.task('docs', ['clean-docs'], () => {
    let config = require('./.esdoc.json');

    return gulp.src([
        'src',
    ])
        .pipe(esdoc(config));
});

/home/exos/alpha/expressolite-project/expressolite/node_modules/gulp-esdoc/index.js:42
    ESDoc.generate(config, publisher);
          ^

TypeError: ESDoc.generate is not a function
    at DestroyableTransform.flush [as _flush] (/home/exos/alpha/expressolite-project/expressolite/node_modules/gulp-esdoc/index.js:42:11)
    at DestroyableTransform.<anonymous> (/home/exos/alpha/expressolite-project/expressolite/node_modules/readable-stream/lib/_stream_transform.js:115:49)
    at Object.onceWrapper (events.js:293:19)
    at emitNone (events.js:86:13)
    at DestroyableTransform.emit (events.js:188:7)
    at prefinish (/home/exos/alpha/expressolite-project/expressolite/node_modules/readable-stream/lib/_stream_writable.js:494:12)
    at finishMaybe (/home/exos/alpha/expressolite-project/expressolite/node_modules/readable-stream/lib/_stream_writable.js:502:7)
    at endWritable (/home/exos/alpha/expressolite-project/expressolite/node_modules/readable-stream/lib/_stream_writable.js:514:3)
    at DestroyableTransform.Writable.end (/home/exos/alpha/expressolite-project/expressolite/node_modules/readable-stream/lib/_stream_writable.js:484:41)
    at DestroyableTransform.onend (/home/exos/alpha/expressolite-project/expressolite/node_modules/vinyl-fs/node_modules/readable-stream/lib/_stream_readable.js:523:10)

Plugin does not use stream to generate docs

I've been trying to use this plugin to generate my docs, and it doesn't seem to be working as anticipated. I tried using the config object as specified in the README:

gulp.task('docs', function() {
  gulp.src(path.join(paths.server, 'routes'))
    .pipe(esdoc({ destination: path.join(paths.docs, 'generated') }));
});

And I got an AssertionError from this line in esdoc. I updated my gulp task to include the source key in the config object:

gulp.task('docs', function() {
  gulp.src(path.join(paths.server, 'routes'))
    .pipe(esdoc({ source: paths.server, destination: path.join(paths.docs, 'generated') }));
});

And verified that docs are being emitted from files in directories within paths.server that are not routes. This leads me to believe that file.path isn't defined, which seems to be born out by the vinyl docs, which specify that path is an "Absolute pathname string or undefined."

For reference, I've also filed an issue about the less-than-ideal error handling in esdoc.generate here, and here's the full error trace:

» gulp docs 
[22:04:47] Using gulpfile ~/workplace/yodel/gulpfile.js
[22:04:47] Starting 'docs'...
[22:04:47] Finished 'docs' after 7.02 ms
fs.js:813
  return binding.readdir(pathModule._makeLong(path));
                 ^

Error: ENOENT: no such file or directory, scandir 'server/**/*.js'
  at Error (native)
  at Object.fs.readdirSync (fs.js:813:18)
  at Function._walk (/home/doug/workplace/yodel/node_modules/gulp-esdoc/node_modules/esdoc/out/src/ESDoc.js:376:37)
  at Function.generate (/home/doug/workplace/yodel/node_modules/gulp-esdoc/node_modules/esdoc/out/src/ESDoc.js:125:12)
  at DestroyableTransform.flush [as _flush] (/home/doug/workplace/yodel/node_modules/gulp-esdoc/index.js:31:11)
  at DestroyableTransform.<anonymous> (/home/doug/workplace/yodel/node_modules/gulp-esdoc/node_modules/through2/node_modules/readable-stream/lib/_stream_transform.js:123:12)
  at DestroyableTransform.g (events.js:260:16)
  at emitNone (events.js:67:13)
  at DestroyableTransform.emit (events.js:166:7)
  at prefinish (/home/doug/workplace/yodel/node_modules/gulp-esdoc/node_modules/through2/node_modules/readable-stream/lib/_stream_writable.js:492:12)
  at finishMaybe (/home/doug/workplace/yodel/node_modules/gulp-esdoc/node_modules/through2/node_modules/readable-stream/lib/_stream_writable.js:500:7)
  at endWritable (/home/doug/workplace/yodel/node_modules/gulp-esdoc/node_modules/through2/node_modules/readable-stream/lib/_stream_writable.js:512:3)
  at DestroyableTransform.Writable.end (/home/doug/workplace/yodel/node_modules/gulp-esdoc/node_modules/through2/node_modules/readable-stream/lib/_stream_writable.js:477:5)
  at DestroyableTransform.onend (/home/doug/workplace/yodel/node_modules/gulp/node_modules/vinyl-fs/node_modules/through2/node_modules/readable-stream/lib/_stream_readable.js:523:10)
  at DestroyableTransform.g (events.js:260:16)
  at emitNone (events.js:72:20)
  at DestroyableTransform.emit (events.js:166:7)
  at /home/doug/workplace/yodel/node_modules/gulp/node_modules/vinyl-fs/node_modules/through2/node_modules/readable-stream/lib/_stream_readable.js:965:16
  at doNTCallback0 (node.js:407:9)
  at process._tickCallback (node.js:336:13)

TypeError: ESDoc.generate is not a function

I just got this message.

manual is not generated with gulp task but works fine in normal esdoc

tried to create a manual entry for my project , at first with a simple overview, it does not work for the plugin but works fine if created with a command to esdoc.