Supporting Typedoc v0.20.x

[favna]

Typedoc did it once again, they released a new version that breaks this extremely useful plugin in many ways. To keep up to date with things it would be nice if this library would be updated to support the latest Typedoc.

For the migration guide for Typedoc see: https://github.com/TypeStrong/typedoc/releases/tag/v0.20.0

[marcj]

Uh, that's pretty big change for a minor version.

[favna]

Sadly... That's how semver works. Any minor version bump in the 0.x.y major version is basically the same as a major version bump starting 1.x.y.

[jevonearth]

Hi @marcj

Is v0.20.0 on the horizon?

[efokschaner]

Note there's also a discussion in the main project about potentially having core support for monorepos https://github.com/TypeStrong/typedoc/issues/1548 (I suggested via Yarn workspaces perhaps)

[marcj]

Yupp, it seems typedoc supports that now out of the box. The following command builds the docs correctly:

typedoc --packages 'packages/*

[efokschaner]

Also, if your root package.json defines your workspaces, you can pass the dir of the root package json, eg. typedoc --packages .

[favna]

I tried this in https://github.com/sapphiredev/utilities and it tried to build a file in node_modules which then failed because it couldn't find a matching tsconfig file.

Typedoc's solution also reads the "main" property in each workspace packages' package.json which will obviously go to the dist/index.js like file for publishing but that caused it to crash and burn hard because it wasn't reading source TS files anymore.

[marcj]

@Favna you have to build TS before using typedoc then.

[marcj]

@Favna I took a look in your repo, and there are a few errors:

• .d.ts should not be in src. Put it into packages/<name>/types and configure tsconfig.json accordingly. For example

      "typeRoots": ["node_modules/@types", "types"],
      "types": [
          "twemoji-parser/dist/lib/regex"
      ]

• You have in src a tsconfig that overwrites sourceMap to false. Not sure why you put a tsconfig in each src, but sourceMap needs to be true in order to get typedoc working after a build. You can exclude sourcemap files via npmignore.

[favna]

@marcj Thanks for looking into it. I've tried again but I can't get it to work quite yet. I've pushed my changes to a branch if you want to have another look: https://github.com/sapphiredev/utilities/tree/feat/upgrade-typedoc

I have removed all the tsconfig.json files from the src directories. The were there because of composite builds, but I moved all those properties to the each package's own tsconfig.json now.

Some observations:

• Specifying "typeRoots" + "types" doesn't actually get discord-utilities to compile. For whatever reason the only thing I can do to make it compile is add "types" to the "includes" array.
• Running typedoc --packages ./packages/prettier-config --packages/utilities to check if it does properly do those 2 results in prettier-config going fine, but utilities only gets arrayStrictEquals documented. I don't know why this is, but my hunch is that it is because we build the TS code with Rollup rather than with tsc (which is an intentional choice, as we want to offer CJS, ESM and UMD variants)
• I also ran yarn docs --packages .\packages\prettier-config\ --packages .\packages\event-iterator\ --packages .\packages\stopwatch\ --packages .\packages\utilities\ --packages .\packages\eslint-config\ --packages .\packages\snowflake\ --packages .\packages\embed-jsx\ --packages .\packages\time-utilities\ which gets it all to output fine I would still expect way more stuff than what I actually get.

Note if you're checking out the branch, to make it compile note the thing of typeRoots, what works for compiling is putting this in packages/discord-utilities/tsconfig.json:

{
    "extends": "../ts-config/src/tsconfig.json",
    "compilerOptions": {
        "target": "ES2020",
        "module": "ESNext",
        "rootDir": "src",
        "outDir": "dist",
        "tsBuildInfoFile": "dist/.tsbuildinfo",
        "composite": true
    },
    "include": ["src", "types"]
}