Improve the "JSON" view to include generic parameters

[ericmorand]

This is a follow up to the very nice implementation of the feature request Add JSON view for interfaces.

Would it be possible to have the generic parameters displayed in the JSON view? In its current state, it looks a bit strange to have some properties of an interface typed with a type that is not resolved to anything, like in the following example:

https://twing-api.nightlycommit.com/interfaces/TwingBaseNode.html

Here, attributes, children and type have types that don't reference anything. Of course, they are defined later on in the page, but it still seems off to have types in the JSON view that don't reference anything.

Something like that would be cool:

interface TwingBaseNode<
    Type extends string | null = any,
    Attributes extends TwingBaseNodeAttributes = TwingBaseNodeAttributes,
    Children extends TwingBaseNodeChildren = TwingBaseNodeChildren
> {
    attributes: Attributes;
    children: Children;
    column: number;
    line: number;
    tag: null | string;
    type: Type;
    execute(executionContext): Promise<any>;
}

[Gerrit0]

PR welcome!

[ericmorand]

@Gerrit0 sorry to be a pain in the a** but I'd like to propose a PR and before that I need to understand how theme development works. But I can't even succeed at creating the most basic plugin that exposes a theme that inherit from the default one.

I'm basing my work on the following documentation:

https://github.com/TypeStrong/typedoc/blob/master/internal-docs/custom-themes.md

TypeDoc 0.22 changed how themes are defined, necessarily breaking compatibility with all Handlebars based themes created for TypeDoc 0.21 and earlier. In 0.22+, themes are defined by plugins calling the defineTheme method on Application.renderer when plugins are loaded. The most trivial theme, which exactly duplicates the default theme can be created by doing the following:

import { Application, DefaultTheme } from "typedoc";

export function load(app: Application) {
    app.renderer.defineTheme("mydefault", DefaultTheme);
}

So, I started by exactly this ^.

When I reference my plugin, and then the theme, to typedoc CLI, it is used successfully but the rendering is totally broken:

ericmorand@janet:~/Projects/twing$ typedoc src/lib.ts --out public --plugin typedoc-theme-2021 --theme mydefault
[info] Loaded plugin typedoc-theme-2021
[warning] TypeDoc has been loaded multiple times. This is commonly caused by plugins which have their own installation of TypeDoc. The loaded paths are:
        /home/ericmorand/.nvm/versions/node/v16.20.2/lib/node_modules/typedoc
        /home/ericmorand/Projects/typedoc-theme-2021/node_modules/typedoc
[info] Documentation generated at ./public

I am definitely doing something wrong but since I'm just starting and following the documentation strictly, I don't know where to start to fix the issue.

Any help would be appreciated.

[Gerrit0]

Thanks for being willing to help out!

[warning] TypeDoc has been loaded multiple times. This is commonly caused by plugins which have their own installation of TypeDoc.

This warning is the cause of the rendering issues. TypeDoc relies on an theme instanceof DefaultTheme check to determine if the assets should be copied into the output folder, and since your typedoc theme project uses its own installation of typedoc, that check fails. There's likely other subtly broken things too, this is just the most obvious.

Personally, the way I usually work around this when developing plugins is to run TypeDoc from the plugin's installation. If you use ../typedoc-theme-2021/node_modules/typedoc/bin/typedoc instead of typedoc as your command, it will probably work.

[ericmorand]

Actually I found that installing typedoc and themes globally was also triggering the "loaded multiple times" issue because of this bug (or feature) of npm:

npm/cli#7057

The workaround is to use the --legacy-peer-deps flag, and since I'm sure it will never get fixed in npm, maybe it could be added as a note in the typedoc documentation. What do you think?

[Gerrit0]

Good idea, added!