Typedoc issues when generating addon docs
opened this issue · comments
I'm mainly just documenting the current dilemma, options that may be used, and why. Feel free to skip down to the tl;dr.
- TypeDoc doesn't play well with ambient declarations by themselves or when merging (lots of issues)
- TypeStrong/typedoc#447
- The issue above describes the output that we get when using the
excludeNotExportedoption. This option is preferred for xterm's addons as Typedoc would otherwise generate docs for module level variables and functions by default. Consider the webLinks addon which has a ton of variables that shouldn't be apart of the documentation. The major pitfall appears when trying to generate both the terminal and addon docs using the same TypeDoc application instance. If they're generated separately, the addon docs won't link back to the terminal.
- Trying to reuse TypeDoc application instances currently can cause plugin already loaded errors.
- I'm not sure this is entirely unintended as they use the same component system to load internal components that do not error and plugins can use
app.converter.hasComponent('name')to check for this. Where converter is just another component/plugin. - The only external TypeDoc plugin in use, typedoc-plugin-markdown which is required to output markdown, chokes on this. It might be worth opening an issue there. Also note that typedoc might bark about being unable to load a plugin because of this even when docs are successfully generated.
- I'm not sure this is entirely unintended as they use the same component system to load internal components that do not error and plugins can use
- Neither the
@hiddennor the synonymous@ignoreannotations span multiple lines.- I don't think this is a bug but it makes not using the
excludeNotExportedoption an unacceptable comprimise IMO.
- I don't think this is a bug but it makes not using the
tl;dr
Certain output options between the terminal and addons are conflicting and TypeDoc may have plugin errors when being used twice in the same node process.
I have a work around for the plugin error if we must generate the terminal and addons separately.
How should we aim to generate docs for the addons once they are moved to separate repositories?
I was assuming that the terminal and addons were all being generated separately in sequence, was this not the case? 😄
Nay, #47 Uses only two TypeDoc application instances to generate the terminal and then the addon docs. The addons don't reference each other so it would seem that way but is not so. I patched typedoc-plugin-markdown locally, stopped using gulp-typedoc, and thought the problem was resolved. Until recently when I removed node_modules... I kinda forgot about the patch or I wouldn't have opened the PR. 😞