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.
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:
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.