fix: typedoc samples and plugin support

[martinsafsten]

Status

HOLD

Description

Configured TypeDoc plugins were always overwritten by typedoc-plugin-markdown. Fixed so that they are merged,
NOTE: I had to add the plugin to the packages/orval package.json for the plugins to resolve. I'm guessing its because its orval itself that initializes the typedoc generation, not the end users project. This might work properly when Orval is deployed as a npm package, and everything is stored in the same node_modules, but it did not work in our samples. Help wanted figuring this out!

Added three samples generating TypeDoc documentation in react-app. One for markdown, one for html, and one for html with extra configured plugin.

Added "theme": "markdown" to the default configuration, which seem to be required now in TypeDoc.

Updated the documentation to link to the samples

Related PRs

List related PRs against other branches:

branch	PR
master	link

Todos

• Tests
• Documentation
• Changelog Entry (unreleased)

[melloware]

@Marfyy so do you still have issues it's hard to tell?

[martinsafsten]

@melloware, sorry for the confusion. It's been a trial and error journey. I'll try and clear things up.

I believe that typedoc works now as before we bumped the ESM based version. Adding "theme": "markdown" to the default config solved it.

I added the doc generation to the samples because I think it is a good addition in general, especially with this ExperimentalWarning from node. It gives us a chance of catching any issues early.

When debugging this, I found that Orval was overriding any plugins that the user added to their config, with the markdown plugin. This was not a documented limitation in Orval, so I figured it was a bug.

After fixing the plugin config, I wanted a sample with a plugin to verify that it was loaded and used correctly. That's when I realized that adding the plugin npm to the sample project was not being resolved because Orval was executing the TypeDoc bootstrapping, not the sample project. So I added the plugin to orvals devDependencies because it's only used when updating samples and running tests.

Orval is linked into the sample through a turborepo link, not an npm package. So my theory is that the plugins will get resolved correctly when Orval and the plugins are added together as dependencies. However, I can not verify this using samples in source code. To verify this, you would need to try it "for real" with Orval through npm. That's the asking for help part. Can we do that without a real release?

When writing this up, I realized that I have mixed two things into one PR. 1. Fixing markdown as the default format, and 2. Fixing TypeDoc plugins. Maybe it would be better to split them up.

[melloware]

Nope all good just wanted to make sure it was ready