[Bug] jsdoc2md bad call to jsdoc: Path-Problem

[Bizarrus]

Executing jsdoc fails because jsdoc2md does not check or correct paths.

File Structure:

Main Path: E:/ServerManager - Master/
- Bin/Docs.js (this generator, see Sample)
- main.js (Main file)
- Docs/ (later the output)

Sample:

#!/usr/bin/node
import jsdoc2md from 'jsdoc-to-markdown'
import { promises as fs } from 'node:fs'
import path from 'path'

/* input and output paths */
const inputFile = './main.js'

/* get template data */
const templateData = await jsdoc2md.getTemplateData({ files: inputFile })

/* reduce templateData to an array of class names */
const classNames = templateData.filter(i => i.kind === 'class').map(i => i.name)

/* create a documentation file for each class */
for (const className of classNames) {
    const template = `{{#class name="${className}"}}{{>docs}}{{/class}}`
    console.log(`rendering ${className}, template: ${template}`)
    const output = await jsdoc2md.render({ data: templateData, template: template })
    await fs.writeFile(path.resolve(`${className}.md`), output)
}

Output:

PS E:\ServerManager - Master> npm run docs

> [email protected] docs
> node ./Bin/Docs.js

file:///E:/ServerManager%20-%20Master/node_modules/jsdoc-api/lib/explain.js:40
      const jsdocErr = new Error(jsdocOutput.stderr.trim() || firstLineOfStdout || 'Jsdoc failed.')
                       ^

JSDOC_ERROR: Jsdoc failed.
    at Explain._runJsdoc (file:///E:/ServerManager%20-%20Master/node_modules/jsdoc-api/lib/explain.js:40:24)
    at process.processTicksAndRejections (node:internal/process/task_queues:95:5)
    at async Explain.execute (file:///E:/ServerManager%20-%20Master/node_modules/jsdoc-api/lib/jsdoc-command.js:57:16)
    at async JsdocToMarkdown.getTemplateData (file:///E:/ServerManager%20-%20Master/node_modules/jsdoc-to-markdown/index.js:68:23)
    at async file:///E:/ServerManager%20-%20Master/Bin/Docs.js:10:22 {
  cause: Error: Command failed: node E:\ServerManager - Master\node_modules\jsdoc\jsdoc.js  -X ./main.js
  node:internal/modules/cjs/loader:1222
    throw err;
    ^
  
  Error: Cannot find module 'E:\ServerManager'
      at Module._resolveFilename (node:internal/modules/cjs/loader:1219:15)
      at Module._load (node:internal/modules/cjs/loader:1045:27)
      at TracingChannel.traceSync (node:diagnostics_channel:315:14)
      at wrapModuleLoad (node:internal/modules/cjs/loader:215:24)
      at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:158:5)
      at node:internal/main/run_main_module:30:49 {
    code: 'MODULE_NOT_FOUND',
    requireStack: []
  }

  Node.js v22.5.1

      at genericNodeError (node:internal/errors:983:15)
      at wrappedFn (node:internal/errors:537:14)
      at ChildProcess.exithandler (node:child_process:421:12)
      at ChildProcess.emit (node:events:520:28)
      at maybeClose (node:internal/child_process:1105:16)
      at ChildProcess._handle.onexit (node:internal/child_process:305:5) {
    code: 1,
    killed: false,
    signal: null,
    cmd: 'node E:\\ServerManager - Master\\node_modules\\jsdoc\\jsdoc.js  -X ./main.js',
    stdout: '',
    stderr: 'node:internal/modules/cjs/loader:1222\r\n' +
      '  throw err;\r\n' +
      '  ^\r\n' +
      '\r\n' +
      "Error: Cannot find module 'E:\\ServerManager'\r\n" +
      '    at Module._resolveFilename (node:internal/modules/cjs/loader:1219:15)\r\n' +
      '    at Module._load (node:internal/modules/cjs/loader:1045:27)\r\n' +
      '    at TracingChannel.traceSync (node:diagnostics_channel:315:14)\r\n' +
      '    at wrapModuleLoad (node:internal/modules/cjs/loader:215:24)\r\n' +
      '    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:158:5)\r\n' +
      '    at node:internal/main/run_main_module:30:49 {\r\n' +
      "  code: 'MODULE_NOT_FOUND',\r\n" +
      '  requireStack: []\r\n' +
      '}\r\n' +
      '\r\n' +
      'Node.js v22.5.1\r\n'
  }
}

Node.js v22.5.1

[75lb]

Hi, thanks for the report! Can you confirm which jsdoc2md version you're using? In the meantime, try overriding the JSDOC_PATH with a new path which has the spaces escaped. I can't remember the exact windows syntax, something like:

set JSDOC_PATH="E:\ServerManager%20-%20Master\node_modules\jsdoc\jsdoc.js" && node ./Bin/Docs.js

[75lb]

Or you could set the env variable in ./Bin/Docs.js, add this line:

process.env.JSDOC_PATH = 'E:\ServerManager%20-%20Master\node_modules\jsdoc\jsdoc.js'

Let me know if that helps. Either way, I will look into reproducing and fixing this bug later today.

[Bizarrus]

Node:   v22.5.1
NPM:    10.9.0

I use the latest version of npm when installing the package (this is the default behavior you should always assume when there is a recent bug report):

npm install jsdoc-to-markdown

"jsdoc": "^4.0.4",
"jsdoc-to-markdown": "^9.0.4",

I would be very grateful if this could be reproduced and also fixed. The bug report is used for information purposes, so that exceptions can also be checked or handled here. Without validation, it is always hoped that the user input is valid.

I have already changed my entire development envionment and am not setting it up again with the aforementioned folder name.

[75lb]

I would be very grateful if this could be reproduced and also fixed

Don't worry, it will be fixed very soon once I'm free.

I am not setting it up again with the aforementioned folder name.

I didn't suggest you change the folder name, I suggested that you try setting an environment variable which is the same folder name but with the space characters replaced with %20 (escape character).

Nevermind, will get back to you once it's fixed.

[75lb]

this is the default behavior you should always assume when there is a recent bug report

No it's not - there are still plenty of users using jsdoc2md v1 which is almost 10 years old.. Some corporate users in regulated environments operate very old builds which they can't change without a formal process.

[75lb]

Fixed and released in v9.0.5. Let me know if you find anything else!