[POC] Try out TypeDoc to generate API reference docs

[michaldudak]

https://typedoc.org/

[netlify]

✅ Deploy Preview for base-ui ready!

Name	Link
🔨 Latest commit	ec324d6
🔍 Latest deploy log	https://app.netlify.com/sites/base-ui/deploys/67be3015ff31940008e046a7
😎 Deploy Preview	https://deploy-preview-1479--base-ui.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[flaviendelangle]

For context, we removed Typedoc from the X repo a few years ago because it was not flexible enough to handle the whole doc generation.
Which meant we had to do 2 AST parsing (one inside Typedoc and one for the analysis that did not use Typedoc), causing a massive perf overhead on the doc gen.

The codebase of the Base UI repo is not that big for now, but I'd stay careful about this aspect.

[michaldudak]

I'm reaching similar conclusions after exploring it for a few hours, even for Base UI. We can't process types that are not exported (exist only to document classes or data attributes) nor we have implementation details. I'm going to look into its plugins so that we can perhaps overcome some of its limitations.
Do you remember what features were missing for X so you decided to go with a custom solution?

[flaviendelangle]

Do you remember what features were missing for X so you decided to go with a custom solution?

Not exactly
I suspect that creating this table from the interface that registers all the events was not easy to do with TypeDoc.
Or other similars stuff where I don't just want to list some props / params basically.

And I also came to the conclusion that it was not that much harder to work with the AST directly when you start to have stuff that is not fully handled by TypeDoc.