docs for public

[zeroasterisk]

multiple docs changes.

To try this locally:

python -m venv .venv
source .venv/bin/activate
pip install --index-url https://pypi.org/simple/ -r requirements-docs.txt
mkdocs serve

[dmandar]

Would recommend having the lit client here..it has more styling options.

[dmandar]

I checked in a script for lit similar to angular..installs deps, runs agents and starts shell app that runs both agents:

cd samples/client/lit
npm run demo:all

Restaurant app at: http://localhost:5173/
Contacts app at: http://localhost:5173/?app=contacts

[dmandar]

Let's land this and iterate as required.

[jacobsimionato]

Hey this is great overall, but there are many incorrect example snippets. I started trying to suggest fixes for them all, but I think the more efficient way is to describe then here, and then you can get Gemini to fix them for you, or we can in a follow up PR.

I think a lot of the confusion here comes from v0.8 vs v0.9. We should write all the docs for v0.8 right now, because that's what all the renderers and agent samples use, so it's the only way we can give people a cohesive story.

v0.9 is purely a spec proposal at this point!

Make sure all snippets match v0.8 schema as shown in specifications/v0.8.

Some specific issues:

• When referring to "children" use "explicitList" or "template" attributes.
• When using literal leaf values, use typed names e.g. "literalString" rather than just "literal".
• There is no createSurface message in v0.8

Make sure code snippets match APIs from actual renderers

It seems like there are some APIs here which don't exist? E.g A2uiRenderer etc?

[jacobsimionato]

Hey this is great overall, but there are many incorrect example snippets. I started trying to suggest fixes for them all, but I think the more efficient way is to describe then here, and then you can get Gemini to fix them for you, or we can in a follow up PR.

I think a lot of the confusion here comes from v0.8 vs v0.9. We should write all the docs for v0.8 right now, because that's what all the renderers and agent samples use, so it's the only way we can give people a cohesive story.

v0.9 is purely a spec proposal at this point!

Make sure all snippets match v0.8 schema as shown in specifications/v0.8.

Some specific issues:

• When referring to "children" use "explicitList" or "template" attributes.
• When using literal leaf values, use typed names e.g. "literalString" rather than just "literal".
• There is no createSurface message in v0.8

Make sure code snippets match APIs from actual renderers

It seems like there are some APIs here which don't exist? E.g A2uiRenderer etc?

[jacobsimionato]

Added more comments for the rest of the files

[jacobsimionato]

This are from v0.9 - in v0.8 it's surfaceUpdate, dataModelUpdate, beginRendering and deleteSurface

[jacobsimionato]

Let's land this and iterate as required.

I defer to people with more experience with these kinds of launches, but I'm a bit worried that it'll be too much work to make these docs accurate in 24 hours. I think it might make sense to try to commit a smaller number of accurate docs, so as we build up more, our agents don't get confused by misinformation.

I was wondering about an approach like:

1. Try to make this PR much smaller by removing all pages that aren't P0
2. Run an agent over the remaining docs and ask it to ensure everything matches the v0.8 specification documents at @specification/0.8 . I see a lot of inaccuracies here that seem to be based on v0.9, or just hallucinated. For docs that are describing client libraries, point the agent at our example apps and client library code.
3. Let's review these and try to get them accurate
4. Latter, readd add the pages we removed, using agents to make sure they are consistent.

But alternatively, if you want to do a pass and submit I'm fine with that and then tomorrow we can all swarm on updating them one-by-one. If we do that strategy, let's meet up tomorrow so we can divide and conquer.

[jacobsimionato]

Okay, I made a heap of changes and pushed them to the branch - PTAL!

[gspencergoog]

Just partway through review, but here are some comments.

[gspencergoog]

"Stable" is all relative in an "Experimental" repo, but I guess that's implied.

[jacobsimionato]

I think this is close enough as a starting point :-D

[gspencergoog]

This doesn't look great on a dark mode background, but I suppose there's nothing to do about that. I don't think there's any way to select the image based on brightness mode.