Docs & snippets revamp in preparation for 0.22's new APIs

[teh-cmc]

Documentation updates in preparation for the new partial updates and columnar APIs in the upcoming 0.22 release.

There are three big components to this:

• A lot of new snippets, and cleanup of existing ones.
• A handful of new doc pages for the website.
• A migration guide.

Also then there's a bunch of codegen improvements, fixes to existing docs, etc.

Note

I made the conscious decision of not mentioning tagging/sorbet anywhere. It's already a lot of information as-is, and at the moment tags provide no value to end users anyhow. As far are users are concerned, these new APIs exist only because they are a net improvement, and not because they allow us to tag things.
Similarly, no mention of send_dataframes at this point.

Everything is vastly improvable in every way -- feel free to.

New snippets

The new snippets are designed to showcase a few key points:

• Rerun has row-oriented, stateful APIs, that make it easy to get started.
• Rerun also has column-oriented, stateless APIs, when the situation calls for it.
• Both the row-oriented and columnar APIs operate on a "partial update" model.
• The row and columnar API are very consistent, and switching from one to the other requires very little effort and "makes sense".

Specifically, these are the most important snippets to watch out for. They are not only used in the snippet index but also all over the place in the docs:

("Update rows", [
    "archetypes/scalar_row_updates",
    "archetypes/points3d_row_updates",
    "archetypes/transform3d_row_updates",
]),
("Update columns", [
    "archetypes/scalar_column_updates",
    "archetypes/points3d_column_updates",
    "archetypes/transform3d_column_updates",
    "archetypes/image_column_updates",
]),
("Partial updates", [
    "archetypes/points3d_partial_updates",
    "archetypes/transform3d_partial_updates",
    "archetypes/mesh3d_partial_updates",
]),

The choice of archetypes is not random:

• Update rows:
  • archetypes/scalar_row_updates: using a "mono-oriented" archetype
  • archetypes/points3d_row_updates: using a run-of-the-mill "batch-oriented" archetype
  • archetypes/transform3d_row_updates: transforms are hard and important, they deserve special focus
• Update columns:
  • archetypes/scalar_column_updates: using a "mono-oriented" archetype
  • archetypes/points3d_column_updates: using a run-of-the-mill "batch-oriented" archetype
  • archetypes/transform3d_column_updates: transforms are hard and important, they deserve special focus
  • archetypes/image_column_updates: images in a columnar context are important and not trivial to reason about, they deserve special focus
• Partial updates:
  • archetypes/points3d_partial_updates: using a run-of-the-mill "batch-oriented" archetype
  • archetypes/transform3d_partial_updates: transforms are hard and important, they deserve special focus
  • archetypes/mesh3d_partial_updates: mesh in a partial update context are not trivial to reason about, they deserve special focus

All of these snippets have comparisons enabled for all three languages.

Snippet index (rendered)

New documentation

There are 4 new pages:

• Concepts > Chunks and Concepts > Latest-at semantics
  These are the most important ones: they are pretty much a port (also known as a copypasta) of Niko's blog post from a while back -- turns out that a lot of valuable information about Rerun has only ever existed in that blog post for the longest time, and was never formalized in the actual docs.
  These pages teach the user about chunks and latest-at semantics, without which it is impossible to understand why, where and how the partial updates & columnar APIs come into play.
• How to > Send entire columns at once
  This is a rewrite of the existing page that:
  • Explains succintcly why the columnar APIs are useful, and points to Concepts > Chunks for further info.
  • Showcases the new snippets, with inline previews.
  • Demonstrates the relationship between the row and column oriented APIs, with code that shows how to go from one to another and back.
• How to > Send partial updates over time
  A new page that:
  • Explains succintcly that everything in Rerun is a partial update, and points to Concepts > Latest-at semantics for further info.
  • Showcases the new snippets, with inline previews.

Migration guide

Migration guide (rendered).

---

• Fixes New partial updates logging APIs: Docs #8584
• Fixes Tagged columnar updates: docs #8763
• Fixes Tagged columnar updates #8751

[github-actions]

Latest documentation preview deployed successfully.

Result	Commit	Link
✅	0c0dc6e	https://landing-hrkfe7zmi-rerun.vercel.app/docs

^{Note: This comment is updated whenever you push a commit.}

[github-actions]

Web viewer built successfully. If applicable, you should also test it:

• I have tested the web viewer

Result	Commit	Link	Manifest
✅	0c0dc6e	https://rerun.io/viewer/pr/8881	+nightly +main

^{Note: This comment is updated whenever you push a commit.}

[Wumpf]

showing all of those in the api is.. a lot. But I guess rather too much than too little :/

[Wumpf]

Marvelous. Did some small fixes & formulation tweaks here and there but I think this is really really good now already