Support for ignoreCompilerErrors

[Gerrit0]

@Gerrit0 could i ask to bring back ignoreCompilerErrors ? In my case i omit on purpose a lot of typings files to make typdoc faster. It is on purpose and i know it wont have any consequence on my doc.
I could really use that flag. You could set it to false by default.
Thanks

Originally posted by @farfromrefug in #1364 (comment)

[Gerrit0]

The main problem with ignoreCompilerErrors I have is that everyone uses it - and then don't turn it off to make sure docs still build when typedoc crashes due to a bad setup... I'm not basing this off a guess - it's based off several months of tracking issues. Approximately 15% of them were due to compiler errors.

That said, for advanced users I'm not completely against making this possible. Refactoring Converter.convert to take in a ts.Program, with the responsibility for checking errors belonging to the caller. This would allow those users to create a wrapper script, if the extra couple of seconds waiting for docs to build is truly prohibitive.

This refactoring would also make it possible, and in fact fairly straightforward, to use the incremental program watcher API to allow re-running TypeDoc without waiting for type checking.

[farfromrefug]

@Gerrit0 your point is totally understandable . though weird. Myself obviously build my lib with tsc thus with errors report.
The reason I want to disable it is that we huge typings files which are only needed for build and not docs.
I would prefer not to have my buil d time X 2 and that flag would really help

[Gerrit0]

0.20.0-beta.16 contains the necessary changes to be able to run typedoc with a script that acts like ignoreCompilerErrors used to.

Just reiterating - a setup like this is officially unsupported. If you use this, and encounter a bug, make sure the bug can be reproduced with a version that does check for compiler errors.

// @ts-check

const td = require("typedoc");
const ts = require("typescript");

const app = new td.Application();
// For reading typedoc.json - optional
app.options.addReader(new td.TypeDocReader());
// For reading tsconfig.json - essential
app.options.addReader(new td.TSConfigReader());

app.bootstrap({
    // can put other options here too, or in typedoc.json/tsconfig.json
    tsconfig: "tsconfig.json",
    entryPoints: ["src/index.ts"],
});

const program = ts.createProgram(
    app.options.getFileNames(),
    app.options.getCompilerOptions()
);

// Application.convert checks for compiler errors here.

const project = app.converter.convert(
    app.expandInputFiles(app.options.getValue("entryPoints")),
    program
);

app.generateDocs(project, "./docs");
app.generateJson(project, "./docs.json");

[klevison]

@Gerrit0 why am I facing with a "blank" page?

Version: TypeDoc 0.20.0-beta.16

[Gerrit0]

The above script is broken in beta 19+, I had to change the signatures of generateDocs / generateJson due to other changes - they now return a promise.

[berickson1]

I utilizedthe --ignoreCompilerErrors flag to generate docs on a subset of the codebase - allowing references to excluded types to effectively dangle. This made it possible to specify a naming convention for specific files to have docs generated (in my case, a bunch of shared models)

[Gerrit0]

That shouldn't be necessary in 0.20 anymore since we properly use the compiler's functions to initialize with all files, then only document what's requested.

[berickson1]

This really doesn't seem to play well with my setup unfortunately. I'm utilizing composite projects and project references, which is probably where the issues are coming from. I tried the following:
Entrypoint: index.ts for the app

1. Custom tsconfig.json that includes all ts files in the repo - no errors, blank output
2. tsconfig inside the app - typescript error (File '/../otherpackage/file.tsx' is not under 'rootDir' '/../webapp/src'. 'rootDir' is expected to contain all source files.

I can't think of anything else to try & I'm forced to upgrade for typescript 4.1 support that's only in the beta.

[Gerrit0]

Can you point TypeDoc at the root tsconfig that references both projects? I've admittedly never used project references, and have never had a good test case to ensure typedoc works properly with it... if your project is open source, sounds like it might be a good test case for me to look at.

[berickson1]

It's not a public project unfortunately. I do have an example that utilizes project references where this same behaviour manifests. I added a branch with typedoc

https://github.com/berickson1/project-references-demo/tree/typedoc

From there you can run npm run doc and it'll only generate a doc for the readme.

[Gerrit0]

Thanks! I will take a closer look either tomorrow night or this weekend, with the goal of making npm run doc as is work - that's the ideal API there.

[Gerrit0]

Thanks again for the example @berickson1! 0.20.0-beta.26 was just published and adds support for project references. I think this should solve your issue. There are some notes about how it works and potential gotchas in #1414.

[kryops]

Just stumbled upon this as well: Our project uses dependencies from an internal Nexus repository. The API docs are generated as GitLab Pages, but in the GitLab CI environment we currently do not have access to the Nexus repository. Before, we used to just install a few select dependencies there and generate the API docs while setting ignoreCompilerErrors.

After upgrading to 0.20, there are a lot of TypeScript errors caused by dependencies we cannot install in the environment we generate the API docs in, so we are currently stuck on 0.17.0-3, unless we can convince our IT department to set up a proper Nexus authentication 😕

Is using a custom script like in #1403 (comment) still possible with the 0.20 release version?

Edit: I think I got it working, thanks a lot for the template above!

My code:

// @ts-check

const td = require('typedoc');
const ts = require('typescript');

const typedocJson = require('typedoc.json');

/**
 * @param {Object} options
 *  @param {string} options.entryPoint
 *  @param {string} options.outDir
 * @param {Partial<import('typedoc').TypeDocOptions>} [typeDocOptions]
 */
exports.createTypeScriptApiDocs = async ({ entryPoint, outDir }, typeDocOptions) => {
  const app = new td.Application();
  app.options.addReader(new td.TSConfigReader());

  app.bootstrap({
    ...typedocJson,
    entryPoints: [entryPoint],
    tsconfig: 'tsconfig.json',
    ...typeDocOptions,
  });

  const program = ts.createProgram(
    app.options.getFileNames(),
    app.options.getCompilerOptions()
  );

  const project = app.converter.convert(
    app.expandInputFiles(app.options.getValue('entryPoints')),
    program
  );

  if (project) {
    await app.generateDocs(project, outDir);
  } else {
    throw new Error(`Error creating the TypeScript API docs for ${entryPoint}.`);
  }
};

[ivawzh]

I cannot make my mono repo (with ./apps and ./libs) work with multiple tsconfig.json. I will be stuck at the old version as ignoreCompilerErrors is removed.

And honestly, I don't see what is the gain of removing ignoreCompilerErrors as you can default it to false. It's the users' conscious decision to turn it on.

[Gerrit0]

And honestly, I don't see what is the gain of removing ignoreCompilerErrors

It eliminated about 30% of bug reports. When your code has compiler errors, TS does not always honor the API contract, so TypeDoc's code was becoming overly cluttered with checks regarding things that might not be true if there were errors.

You might be interested in #1567, which looks like it might do some good things for monorepos.

[ahamid]

I take from this that typedoc will not produce even partial output for a project that doesn't completely typecheck?

[Gerrit0]

That is correct.

[Nokel81]

My main problem is that I am encountering microsoft/TypeScript#38383 again when I try to upgrade from [email protected] to the latest version. Which I don't get when I run the older version.

[Gerrit0]

Having this option wouldn't fix that issue... and that's in the TypeScript repo, if there's a crash with a version of TS that TypeDoc officially supports (as noted by the peer dependencies) in 0.20, then to fix it I'll need a bug report with a reproduction

[Nokel81]

@Gerrit0 Yes I understand, I am going to wait until 4.3 support roles around to make sure that the issue continues.

[reconbot]

I have another strange usecase, we're using typedoc to generate docs for AssemblyScript which looks like but isn't typescript so therefor doesn't compile, however the docs typedoc generate look great. Unfortunately the workspaces ticket doesn't solve generating docs in my case. I'll have a look at the custom script but I just wanted to add another vote towards bringing back the flag.

[DanielSWolf]

It seems that in recent versions, the signature of Application has changed. When I try running @kryops's script using TypeDoc 0.22.4, I get an error stating that app has no expandInputFiles method. In addition, the signature of app.converter.convert() seems to have changed as well, now allowing only a single argument.

Is there a way to ignore compiler errors on TypeDoc 0.22.4?

[Gerrit0]

In 0.22, you want app.getEntryPoints(), which can be passed to app.converter.convert as before

[DanielSWolf]

Thank you! With this, I got @kryops's function working with TypeDoc 0.22. Here it is, in case someone else is in the same situation (converted it to TypeScript):

import path from 'path';
import { TSConfigReader, Application as TypeDocApplication, TypeDocOptions } from 'typedoc';

import typedocJson from './typedoc.json';

export async function createTypeScriptApiDocs(
  { entryPoint, outDir }: { entryPoint: string, outDir: string },
  typeDocOptions?: Partial<TypeDocOptions>,
) {
  const app = new TypeDocApplication();
  app.options.addReader(new TSConfigReader());

  app.bootstrap({
    ...typedocJson,
    entryPoints: [entryPoint],
    tsconfig: path.join(__dirname, '../tsconfig-typedoc.json'),
    ...typeDocOptions,
  });

  // This is the part that seems to skip compile errors
  // (normally we would call `app.convert()` here)
  const project = app.converter.convert(app.getEntryPoints() ?? []);

  if (!project) {
    throw new Error(`Error creating the TypeScript API docs for ${entryPoint}.`);
  }

  await app.generateDocs(project, outDir);
}

[Gerrit0]

Against my better judgement, I've decided to give this option another shot. #1975 introduces a --skipErrorChecking option, which is available in 0.23.11.

[Atul227]

Thank you! With this, I got @kryops's function working with TypeDoc 0.22. Here it is, in case someone else is in the same situation (converted it to TypeScript):

import path from 'path';
import { TSConfigReader, Application as TypeDocApplication, TypeDocOptions } from 'typedoc';

import typedocJson from './typedoc.json';

export async function createTypeScriptApiDocs(
  { entryPoint, outDir }: { entryPoint: string, outDir: string },
  typeDocOptions?: Partial<TypeDocOptions>,
) {
  const app = new TypeDocApplication();
  app.options.addReader(new TSConfigReader());

  app.bootstrap({
    ...typedocJson,
    entryPoints: [entryPoint],
    tsconfig: path.join(__dirname, '../tsconfig-typedoc.json'),
    ...typeDocOptions,
  });

  // This is the part that seems to skip compile errors
  // (normally we would call `app.convert()` here)
  const project = app.converter.convert(app.getEntryPoints() ?? []);

  if (!project) {
    throw new Error(`Error creating the TypeScript API docs for ${entryPoint}.`);
  }

  await app.generateDocs(project, outDir);
}

How to use it in my project