--entryPoints not recognized in typedoc in packages strategy

[nicfv]

Search terms

entry, points, packages, strategy

Expected Behavior

This is for the entry point strategy of packages only.

When I move the "entryPoints" from the config file typedoc.json into the typedoc script, all of a sudden I get the warning: No entry points were provided, this is likely a misconfiguration. And, no documentation is generated for that package. When I run typedoc in the package directory (instead of the base directory) it still works fine with no warnings or errors. The warning only occurs when I do npm run docs in the base directory. See the steps for more details.

$ npm run docs

> [email protected] docs
> typedoc

[info] Converting project at ./packages/lib
[info] Converting project at ./packages/shared-assets
[info] Converting project at ./packages/wrapping-lib
[info] Merging converted projects
[info] Documentation generated at ./docs

Actual Behavior

$ npm run docs

> [email protected] docs
> typedoc

[info] Converting project at ./packages/lib
[info] Converting project at ./packages/shared-assets
[info] Converting project at ./packages/wrapping-lib
[warning] No entry points were provided, this is likely a misconfiguration.
[info] Merging converted projects
[info] Documentation generated at ./docs

Steps to reproduce the bug

Clone

git clone [email protected]:Gerrit0/typedoc-packages-example.git

packages/wrapping-lib/typedoc.json

{
  "extends": ["../../typedoc.base.json"],
- "entryPoints": ["src/index.ts"]
}

packages/wrapping-lib/package.json

  "scripts": {
-   "docs": "typedoc --out docs"
+   "docs": "typedoc --entryPoints src/index.ts --out docs"
  }

Run the docs script

npm run docs

Environment

• Typedoc version: 0.25.13
• TypeScript version: 5.4.2
• Node.js version: 20.11.1
• OS: Uubuntu 22.04

[Gerrit0]

This is working as expected. TypeDoc in packages mode does not call TypeDoc in a separate process for each package, it instead reads the configuration file and executes in that package.

[nicfv]

Backstory: I was converting my mono-style repo into using the packages strategy so clean things up a bit. I am using typedoc.json files, but still had several command line arguments including --entryPoints. (I was using the shorthand typedoc [entryPoints] instead of spelling out.) I was not getting any documentation except for the readme files, with the same warnings as above. It took me an embarrassingly long time to figure out what the issue was...

Luckily, the workaround is very easy, and is probably better practice to keep everything in the typedoc.json config file instead of leaving it as command line arguments anyway. However, this behavior definitely feels like a bug and was difficult to track down; because like I said, if you run typedoc directly from the package directory, it works just fine with no errors at all. E.g.:

cd packages/wrapping-lib
npm run docs

[nicfv]

TypeDoc in packages mode does not call TypeDoc in a separate process for each package, it instead reads the configuration file and executes in that package.

OHH.... I think I understand now. I was confused when looking at the source in your packages example. I was under the impression that typedoc was called (by npm run docs) in each package directory. I guess it makes a little more sense this way now.

The main downside is that you need a typedoc.json containing this in every one of your packages, assuming you are using the same base for everything.

{
  "extends": ["../../typedoc.base.json"],
  "entryPoints": ["src/index.ts"]
}

I tried putting entryPoints in typedoc.base.json, and this is what I got:

$ npm run docs

> [email protected] docs
> typedoc

[info] Converting project at ./packages/lib
TypeDoc exiting with unexpected error:
Error: ENOENT: no such file or directory, scandir '/home/nic/Desktop/typedoc-packages-example/src'
    at Object.readdirSync (node:fs:1515:26)
    at glob (/home/nic/Desktop/typedoc-packages-example/node_modules/typedoc/dist/lib/utils/fs.js:253:32)
    at /home/nic/Desktop/typedoc-packages-example/node_modules/typedoc/dist/lib/utils/entry-point.js:176:38
    at Array.flatMap (<anonymous>)
    at expandGlobs (/home/nic/Desktop/typedoc-packages-example/node_modules/typedoc/dist/lib/utils/entry-point.js:175:31)
    at getEntryPoints (/home/nic/Desktop/typedoc-packages-example/node_modules/typedoc/dist/lib/utils/entry-point.js:78:53)
    at _classThis.getEntryPoints (/home/nic/Desktop/typedoc-packages-example/node_modules/typedoc/dist/lib/application.js:253:53)
    at _classThis.convert (/home/nic/Desktop/typedoc-packages-example/node_modules/typedoc/dist/lib/application.js:275:38)
    at _classThis._convertPackages (/home/nic/Desktop/typedoc-packages-example/node_modules/typedoc/dist/lib/application.js:473:44)
    at async run (/home/nic/Desktop/typedoc-packages-example/node_modules/typedoc/dist/lib/cli.js:96:21) {
  errno: -2,
  code: 'ENOENT',
  syscall: 'scandir',
  path: '/home/nic/Desktop/typedoc-packages-example/src'
}

I understand why that error occurs, I'm just stating it as a minor drawback having to duplicate the same typedoc.json for each package.

[Gerrit0]

Yeah, that downside annoys me too, that's what #2523 is intended to fix, just haven't gotten around to implementing it yet

[nicfv]

Didn't know you already had an issue for this! I do not think there is any action needed for this issue, if I have anything more to add, I'll reply in #2523. Would love to see this implemented, as well as other features I've suggested. If I find the time and motivation, I hope to contribute in the future. This is really a great project.