Consider an alternate implementation for docgen

[philpax]

At present, the docgen works by having the build system generate a dump of the semantic state in ambient_package.json, and then taking that JSON and generating a static site from it. This is simple, makes updating the format for new documentation straightforward, and is easy to redistribute. This was inspired by rustdoc/docs.rs, which takes the same approach.

However, there are a few disadvantages to this approach:

• Changes to the format require regeneration of all existing docs
• There's a lot of duplication, especially with the current implementation that includes the dependencies within the generated docs
• There's limited dynamic elements (no search)

These can be mitigated somewhat by adding JavaScript to enrich the page and by linking to existing packages when they're available.

However, an alternate approach would be to rebuild the entire thing as a SPA and ship the built SPA with Ambient / our hosted docs. This SPA would consume the ambient_package.json (which would be augmented with whatever information was required), and then generate a similar set of views to the current docgen.

This would address the disadvantages above, but we would have to make sure that it still works as you'd expect a normal site to work (routing, navigation, links, etc) - not too hard, but doesn't come for free like a static site does.

The resulting SPA "binary" (React, Dioxus, what have you) can then be bundled into the Ambient application and be served on demand or packaged up with the ambient_package.json (which would then be versioned). This SPA would also be hosted only once on our hosting.

[philpax]

Had a brief chat with Fredrik about this. Dioxus has some growing pains, but the React ecosystem isn't pain-free either. I'm still leaning React + TypeScript and shipping the bundle; even though it's not as strongly-typed as Dioxus + Rust, the iteration speed and smaller output are strong points in its favour.