docs(a2ui): Update documentation to align with v0.9 specification#622
docs(a2ui): Update documentation to align with v0.9 specification#622gspencergoog wants to merge 5 commits intogoogle:mainfrom
Conversation
gspencergoog
requested review from
dmandar,
jacobsimionato and
zeroasterisk
as code owners
- Replaced legacy v0.8 terminology (e.g., `beginRendering` -> `createSurface`, `usageHint` -> `variant`). - Updated schema examples for components and messages throughout the documentation. - Migrated legacy documentation to `docs/v0_8/` archive. - Updated guides and concepts to reflect v0.9 changes. - Add 'fit' and 'variant' properties to Image component documentation. - Clarify 'updateDataModel' value optionality (omission implies deletion). - Add new 'Client-Side Functions' reference page and link it. - Mention client-side formatting in best practices.
gspencergoog
force-pushed
the
update_docs
branch
from
409483c to
519a672
Compare
- Move v0.8 documentation to `docs/specification/`. - Add wrapper files for v0.8, v0.9, v0.10 specifications, evolution guides, and extension specs. - Update mkdocs.yaml to reflect new structure and include all relevant documents. - Update prepare_docs.py to handle file copying, JSON flattening, and comprehensive link rewriting for all versions. - Fix internal links in markdown files to point to correct relative paths. - Remove deprecated `docs/v0_8` directory.
zeroasterisk
left a comment
zeroasterisk
left a comment
There was a problem hiding this comment.
The content updates look accurate, but I think we need version-specific documentation tabs before merging this.
⚠️ Blocking concernUsers on 0.8 renderers visiting the docs will see 0.9 examples that don't work for them. We should add a version switcher (like React/Vue docs have) so users can select their renderer version and see matching examples.
Options:
- Add version tabs to the docs site (preferred) — see React docs or Vue docs
- Maintain separate
/v0.8/and/v0.9/doc paths - At minimum, add prominent "Version: 0.9" badges and link to archived 0.8 docs
Happy to help spec this out if useful. What do you think?
Yeah, I wondered about this too. As for what form this should take, the examples you gave basically just have a banner or a link to the previous versions. React: Vue: And they start off on the "current" version by default. That's sort of what I was going for here anyhow: the 0.8 spec docs are still there, but they're pared down. What if we just do what React does and just keep previous versions as separate sites? I mean, for now, we can just have them at a different URL with the version in it, so we don't need separate host names, but does that sound good? And the bigger question is: do we start people on the 0.9 docs or the 0.8 docs when they go to a21ui.org? |
|
I assume we don't want to go as far as Pyhon does: https://docs.python.org/3/ It has a pulldown to select the version to view. I think only A2UI renderer implementers will be interested in that level of detail, and they can still browse the docs if they are at a separate URL like https://a2ui.org/0.8/quickstart/ So, I'm going to proceed like this: I'll convert this PR so that everything except for the Intro and FAQ tabs are under a version number, and the landing page will explain the different versions and their current state. The stuff under 0.8 will be the original content from 0.8 and the 0.9 content will be this content. The Intro and FAQ tabs will be 0.9 specific in the places where an example is given, and I'll a FAQ about the versions. Sound good @zeroasterisk ? |
2 participants
Description
This updates the docs folder to describe the 0.9 specification instead of 0.8. I added disclaimers that the renderers are not yet up to spec, but I think it's still a little odd to have docs for 0.9 and no examples yet.
Better that the docs represent the current spec, though.