typedoc does not respect tsconfig.json include and entryPoint should be supplied manually.

[hdi-amiri]

Search terms

typedoc, tsconfig, include, exclude

Expected Behavior

I have the following tsconfig.json file:

{
  "compilerOptions": {
    "allowSyntheticDefaultImports": true,
    "allowUnreachableCode": false,
    "declaration": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "lib": ["dom", "es2017"],
    "moduleResolution": "node",
    "module": "commonjs",
    "target": "es2017",
    "inlineSources": true,
    "noImplicitAny": true,
    "outDir": "dist",
    "sourceMap": true,
    "strictNullChecks": true,
    "declarationDir": "dist/types",
    "skipLibCheck": true
  },
  "include": ["src"],
  "exclude": ["node_modules"],
  "typedocOptions": {
    "excludePrivate": true,
    "excludeProtected": true,
    "excludeInternal": true,
    "exclude": [
      "types/jsx.d.ts",
      "**/*+(e2e|spec|index).ts",
      "**/*spec.tsx",
      "**/*.model.ts",
      "**/environment/*.ts",
      "**/components.d.ts",
      "**/components/common/*",
      "**/*+(e2e|spec|index).ts",
      "**/*spec.tsx",
      "**/*.model.ts",
      "**/environment/*.ts",
      "**/core.d.ts"
    ],
    "json": "json-doc",
    "out": "core-doc",
    "name": "core",
    "includeVersion": true,
    "readme": "readme.md",
    "showConfig": false
  }
}

I expect that when I enter the following command in terminal, the output be generated, but It doesn't work.

$ typedoc

But when I change it to this, it works as expcted:

$typedoc src

Actual Behavior

The following output is shown:

$ typedoc
Error: No entry points provided

Steps to reproduce the bug

Environment

• Typedoc version: 0.20.26
• TypeScript version: 4.1.5
• Node.js version: 12.18.2
• OS: Windows

[Gerrit0]

entryPoint should be supplied manually.

Yes! It should.

For the vast majority of cases, the include you give to TypeScript, and the entryPoints you give to TypeDoc should be different. They describe two different features.

include means "all of the files necessary to compile this project"
entryPoints means "what files users of this library may import"

For many projects, entryPoints should be a single file - src/index.ts or similar. TypeDoc will then examine what is exported from that file and document it - leaving your internal functions/modules that consumers of the library should not use undocumented. TypeDoc's own documentation does this:

https://github.com/TypeStrong/typedoc-site/blob/5cf54eb16c05dabf5cd3fd27b36ddbc1ab469401/typedoc.json#L1-L8

{
    "out": "../_site/api",
    "json": "../_site/api/docs.json",
    "name": "TypeDoc Documentation",
    "excludeExternals": true,
    "includeVersion": true,
    "entryPoints": ["src/index.ts"]
}

There has been some discussion in #1485 about automatically detecting the entry point using the main field from package.json, which I'm still considering...

[hdi-amiri]

Thanks for your quick response!
What you say I guess is in contradiction with what is stated here, Or maybe I misinterpreted it!

When TypeDoc loads a tsconfig.json file, it will read options declared under the typedocOptions key and take the tsconfig.json's input files (as defined by files or include/exclude) as the input files.

[Gerrit0]

Oh! That makes sense why you thought what you did then. I must have forgotten to update that part of the page when 0.20 was released. That was accurate for older versions of TypeDoc... I'll update that shortly.

[hdi-amiri]

Thanks!