mkdirp seems to be used incorrectly
chharvey opened this issue · 9 comments
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.
gulp-jsdoc3 is mostly a passthrough to jsdoc3. This sounds like a jsdoc issue or maybe the template you are using. Do you have an example I can try?
@mlucool I've tried to break it down to the bare necessities:
gulpfile.js:
const gulp = require('gulp')
const jsdoc = require('gulp-jsdoc3')
gulp.task('docs:api', function () {
return gulp.src(['README.md', 'index.js', /* ... more ... */], {read:false})
// ^ any js files should work
.pipe(jsdoc(require('./config-jsdoc.json')))
})config-jsdoc.json:
{
"sourceType": "module",
"tags": {
"allowUnknownTags": true,
"dictionaries": ["jsdoc", "closure"]
},
"opts": {
"destination": "./docs/api"
},
"plugins": [
"plugins/markdown"
],
"templates": {
"cleverLinks": false,
"monospaceLinks": false,
"default": {
"outputSourceFiles": true,
"includeDate": false
},
"path": "ink-docstrap",
"theme": "flatly",
"navType": "vertical",
"linenums": false,
"dateFormat": "MMMM Do YYYY, h:mm:ss a"
}
}npm installs (only the relevant ones):
├─┬ gulp@3.9.1
│ ├── archy@1.0.0
│ ├─┬ chalk@1.1.3
│ │ ├── ansi-styles@2.2.1
│ │ ├── escape-string-regexp@1.0.5
│ │ ├── has-ansi@2.0.0
│ │ ├── strip-ansi@3.0.1
│ │ └── supports-color@2.0.0
│ ├── deprecated@0.0.1
│ ├─┬ gulp-util@3.0.8
│ │ ├── array-differ@1.0.0
│ │ ├── array-uniq@1.0.3
│ │ ├── beeper@1.1.1
│ │ ├── chalk@1.1.3 deduped
│ │ ├── dateformat@2.2.0
│ │ ├── fancy-log@1.3.0
│ │ ├── gulplog@1.0.0
│ │ ├── has-gulplog@0.1.0
│ │ ├── lodash._reescape@3.0.0
│ │ ├── lodash._reevaluate@3.0.0
│ │ ├── lodash._reinterpolate@3.0.0
│ │ ├── lodash.template@3.6.2
│ │ ├── minimist@1.2.0 deduped
│ │ ├── multipipe@0.1.2
│ │ ├── object-assign@3.0.0
│ │ ├── replace-ext@0.0.1
│ │ ├── through2@2.0.3 deduped
│ │ └── vinyl@0.5.3
│ ├── interpret@1.0.4
│ ├─┬ liftoff@2.3.0
│ │ ├── extend@3.0.1
│ │ ├── findup-sync@0.4.3
│ │ ├── fined@1.1.0
│ │ ├── flagged-respawn@0.3.2
│ │ ├── lodash.isplainobject@4.0.6
│ │ ├── lodash.isstring@4.0.1
│ │ ├── lodash.mapvalues@4.6.0
│ │ ├── rechoir@0.6.2
│ │ └── resolve@1.5.0
│ ├── minimist@1.2.0
│ ├─┬ orchestrator@0.3.8
│ │ ├── end-of-stream@0.1.5
│ │ ├── sequencify@0.0.7
│ │ └── stream-consume@0.1.0
│ ├── pretty-hrtime@1.0.3
│ ├── semver@4.3.6
│ ├─┬ tildify@1.2.0
│ │ └── os-homedir@1.0.2
│ ├─┬ v8flags@2.1.1
│ │ └── user-home@1.1.1
│ └─┬ vinyl-fs@0.3.14
│ ├── defaults@1.0.3
│ ├── glob-stream@3.1.18
│ ├── glob-watcher@0.0.6
│ ├── graceful-fs@3.0.11
│ ├── mkdirp@0.5.1
│ ├── strip-bom@1.0.0
│ ├── through2@0.6.5
│ └── vinyl@0.4.6
└─┬ gulp-jsdoc3@1.0.1
├── bluebird@3.5.1
├─┬ debug@2.6.9
│ └── ms@2.0.0
├── gulp-util@3.0.8 deduped
├─┬ ink-docstrap@1.3.1
│ ├── moment@2.19.2
│ └── sanitize-html@1.15.0
├─┬ jsdoc@3.5.5
│ ├── babylon@7.0.0-beta.19
│ ├── bluebird@3.5.1 deduped
│ ├── catharsis@0.8.9
│ ├── escape-string-regexp@1.0.5 deduped
│ ├── js2xmlparser@3.0.0
│ ├── klaw@2.0.0
│ ├── marked@0.3.6
│ ├── mkdirp@0.5.1 deduped
│ ├── requizzle@0.2.1
│ ├── strip-json-comments@2.0.1
│ ├── taffydb@2.6.2
│ └── underscore@1.8.3
├── map-stream@0.0.6
└─┬ tmp@0.0.28
└── os-tmpdir@1.0.2
I had the same issue. I specified:
{
"opts": {
"template": "templates/default"
}
}
and the issue disappeared. I imagine the issue is involved in ink-docstrap somehow, either directly, or in the way that this package consumes it.
I think I found the issue, and docstrap/docstrap#316 seems to have solved it. ink-docstrap should be updated to v1.3.2. I'll submit a pull request.
Now that 1.3.2 is out we should default to a working version. Please retest after a clean install. Also npm ls ink-dockstrap to be sure you have the right version.
I can verify that ink-docstrap@1.3.2 fixes the problem, so closing this issue.