Switch to TypeDoc for generating API docs

[zspriggs]

Check for duplicates

• I have searched for similar issues before opening a new one.

Problem

Request

I've been looking into switching to TypeDoc after @maribethb mentioned it and I think it would help resolve a number of API documentation issues.

Pros:

1. We currently have to patch API documenter, which is not ideal for maintenance reasons.
2. We have to do a lot of file/string manipulation to API documenter's output. A lot of this is API documenter specific and would go away. There's also a TypeDoc plugin for Docusaurus that we could use.
3. Method reference docs are missing descriptions #7244 would be partially resolved by switching to TypeDoc, as it is able to inherit descriptions.
4. Add source code links to API docs #10110 would be resolved by switching to TypeDoc, since it includes links automatically.
5. Allow deploying documentation without updating reference docs #10298 would not be any harder with TypeDoc, and might actually be better. You can still follow Option 1, because TypeDoc supports JSON generation and you can generate the docs from there. TypeDoc's links point to a specific commit, so if you had changes to a method that weren't released, it would automatically point to whatever commit it was when you generated the JSON.

Cons:

1. It's hard to get the format of the API docs to be the same as they were with API documenter. Either we a) write/maintain code to get everything to look as similar as possible or b) adopt a different format for the API docs, which would introduce a new learning curve for developers who are used to our API docs as is.
2. TypeDoc has different naming conventions compared to API documenter, so all of our API reference links would be different. In our own guides, we can convert the links, but we would need to consider developers who might have API docs bookmarked. We could:
   a) add a script to convert the TypeDoc names into the API documenter format
   b) provide redirects, but we'd need an aggressive number of them
   c) break everybody's API links
3. I've only just started exploring this so there could be other cons

If we were to convert, we ideally could do it before putting work into the open docs pipeline issues (#10303 and #10298) but that would mean putting those issues on hold for a little while.

Alternatives considered

No response

Additional context

No response

[maribethb]

I'm definitely in favor of doing this, or at the very least standing it up so we can do a comparison between the two outputs.
I'm not worried about making the format the same as api-documenter as I don't love it anyway, and TypeDoc seems more popular so there's a good chance devs are familiar with it from other projects.

Same with breaking bookmarked urls, I think that's an acceptable tradeoff for generally improving the reference docs and hopefully the sidebar navigation makes it easy enough to get back to a page you want.

api-documenter will continue to bring us pain for as long as we have to maintain the two patches we do, and they don't seem interested in resolving the issues that led us to patch it. I also think a lot of the transformation code we have that was brought in by Cybage is... dubious at best and being able to delete it all wholesale in favor of output that's just correct straight from the tool would be a huge win as well.