typedoc.js Stops Working after Writing Configuration in tsconfig.js is Supported.

[ZheyangSong]

I recently started to use typedoc for my new project. But when trying to config the tool via typedoc.js, I can't find good example of how this file should be defined. After some research in the source code, PRs and Issues. It looks like thetypedoc.js doesn't support simple exported json object well (It won't understand most of the options listed in the README.md), though an exported function in the file will receive the tool instance. However, in the tsconfig.json, I can define all exposed config options in a typedocOptions property. It looks like the tsconfig.json can be used to replace typedoc.js, if calling the tool instance in an exported function is not that much important to most users.

[paulsouche]

Hi

My usage of typedoc is

typedoc --options typedoc.json index.ts

with

{
  "mode": "modules",
  "out": "docs",
  "exclude": "test",
  "theme": "default",
  "ignoreCompilerErrors": true,
  "excludePrivate": true,
  "excludeNotExported": "true",
  "target": "ES5",
  "moduleResolution": "node",
  "preserveConstEnums": "true",
  "stripInternal": "true",
  "suppressExcessPropertyErrors": "true",
  "suppressImplicitAnyIndexErrors": "true",
  "module": "commonjs"
}

But since v0.9.0 this usage seems to be broken

cli asked me for a .js file (typedoc.js) instead of a json but this doesn't work

Error module is undefined

module.exports = {
  mode: 'modules',
  out: 'docs',
  exclude: 'test',
  theme: 'default',
  ignoreCompilerErrors: true,
  excludePrivate: true,
  excludeNotExported: 'true',
  target: 'ES5',
  moduleResolution: 'node',
  preserveConstEnums: 'true',
  stripInternal: 'true',
  suppressExcessPropertyErrors: 'true',
  suppressImplicitAnyIndexErrors: 'true',
  module: 'commonjs'
};

Pretty sure I'm missing something here but documentation is not really clear on how to use this to pass typedoc the options

Thx anyway for the great job

[Laroosta]

+1 - Same issue here

[paulsouche]

@Laroosta I didn't read @ZheyangSong issue in the detail but you can add your json in a typedocOptions key of your tsconfig.json

In my case

{
  "compilerOptions": {
     //...
  },
  "typedocOptions": {
    "mode": "modules",
    "out": "docs",
    "exclude": "test",
    "theme": "default",
    "ignoreCompilerErrors": true,
    "excludePrivate": true,
    "excludeNotExported": true,
    "target": "ES5",
    "moduleResolution": "node",
    "preserveConstEnums": true,
    "stripInternal": true,
    "suppressExcessPropertyErrors": true,
    "suppressImplicitAnyIndexErrors": true,
    "module": "commonjs"
  }
}

Your command become

typedoc index.ts

I'm not a big fan of it as tsconfig is used by a lot of third party libraries for their config and often not very well documented... But it works for me.

[Laroosta]

@paulsouche Thanks for the reply.

If I roll back to v0.8.0, it works using the json file. I'll update to v0.9.0 and try your suggestion!

[soren-mou-jakobsen]

I can confirm

typedoc --options typedoc.json

is broken in 0.9.0, but works in 0.8.0. Moving options to tsconfig.json in a typedocOptions section works.

[Itrulia]

Still broken :(

[vojtechruz]

Experiencing this issue too. Are there plans to address it?

[aciccarello]

No one is working on it at the moment but I'd be happy to accept a PR

[jrabbe]

This seems to be broken due to changes in priority for the options readers. Specifically, the typedoc option seems to get the discover event before the argument option. In turn this results in the typedoc option not having a value to read the options file from.

[aciccarello]

I'm in favor of fixing typedoc.json support and dropping typedoc.js support. If people need dynamic control of typedoc, they can require the application directly.

[Tokimon]

Actually my PR: #742 should sort of fix this, as it would now search for both typedoc.js and typedoc.json (however still favoring typedoc.js if both are found), if only given a path (or left unfilled) and not a specific file. So you can basically use your preferred method as you like.

[cancerberoSgx]

I understand the reasons behind this issue but currently, having configuration in .ts or .js files gives a very useful feature out of the box and pretty easy and straight forward: configuration hierarchy (like tsconfig.json "extends"). I'm not saying not to do it but be conscious that if you also don't implement something like tsconfig.json's extends property then users will loose a very very useful feature. Example:

File typedoc-config-base.ts:

module.exports = {
  src: ['./src'],
  mode: 'file',
  includeDeclarations: true,
  tsconfig: 'tsconfig.json',
  excludePrivate: true,
  excludeProtected: true,
  excludeExternals: true,
  readme: 'README.md',
  name: 'my-cool-project',
  ignoreCompilerErrors: true,
  plugin: 'none',
  listInvalidSymbolLinks: true,
};

File typedoc-config-html.ts:

module.exports = {
  ... require('./typedoc-config-base.ts'),
  out: '../docs/html',
}; 

File typedoc-config-md.ts:

module.exports = {
  ... require('./typedoc-config-base.ts'),
  theme: 'markdown',
  plugin: 'typedoc-markdown-plugin',
  out: '../docs/md',
}; 

Wonder If both json and js could be supported ?

[aciccarello]

@cancerberoSgx I can imagine having a .js config file being helpful but my main hesitation is that it seems to make more sense to require typedoc as a node module in that case. It is extra API surface area that only adds a minor improvement.

For the time being, supporting typedoc.js isn't too difficult so I don't think it'll be removed anytime soon.

[Tokimon]

I don't see the advantage of removing the support of the .js as it is already in code and you can use either of the formats that suits your liking. Just because some prefer plain JSON doesn't mean everyone does.

For the majority of people the typedoc CLI is enough and it would be kinda tedious to have to create a file and include typedoc as a module just because you want a bit of dynamic in the config.

Supporting both formats is something many major modules have been doing for years (Webpack or Babel just name a few) and I have the impression that people like that freedom of choice.

So overall just make the handling of both files work and continue the support IMHO.

[ZheyangSong]

Hi folks, I didn't realize that this issue could become somewhat confusing to some followers. The title of this PR was based on my understanding of the code change history up to the moment I opened this issue. There was some commit that removed parsing of js configuration file and added tsconfig.json support. I thus thought the intention was to brace tsconfig.json but still expose a minimal API surface to be used in nodejs modules, thus you can use it to create plugins/loaders. I have no objection to making this tool support multiple configuration formats. Unfortunately, I didn't quite track this issue after being caught by my job... but I'll change the title to avoid confusion...

[ductiletoaster]

Just tried the following:

typedoc --options typedoc.json

And got this error...

Should the use of JSON files be part of another ticket or is it appropriate to track here?

Edit: This was with version 0.14.0
yarn v1.12.3
node v10.15.0

[aciccarello]

@ductiletoaster Could you try typedoc --options=typedoc.json? Also, typedoc looks for a typedoc.json file by default so you may not need to set the flag.

[ductiletoaster]

@aciccarello Unfortunely I am using typedoc in a mono repo and need to resolve each packages config file.

When I run the cmd suggested I get:

typedoc --options=/home/brian/Documents/Development/pixeloven/packages/pixeloven-core/typedoc.json
Error: Unknown option: options=/home/brian/documents/development/pixeloven/packages/pixeloven-core/typedoc.json
error Command failed with exit code 1.

Here is the configuration:

{
    "name": "@pixeloven/core",
    "target": "es5",
    "out": "docs",
    "ignoreCompilerErrors": "false",
    "preserveConstEnums": "true",
    "exclude": "*.test.ts",
    "stripInternal": "false"
}

This works well as a .js file and without the --options=

[ductiletoaster]

Alright in my case I had simply neglected to include the src path after the --options argument.

typedoc --options typedoc.json src

If I ran just

then all the default behaviour would work as expected. After I added the options argument I had assumed that typedoc would still look for src files in the same manner.

From what I can tell this issue should be closed as the default behavior supports searching the current directory for .js and then .json. Alternatively we can provide the --options argument with a src path for either .js or .json.

This was tested with version 0.14.0.

[aciccarello]

Ah, I see. So the input file parsing messed up the argument passing. Thanks for the update.