Add a "Cook book" section to the docs

[emilk]

This would be similar to how-to guides, but focused on code (API usage). It would be longer than archetype snippets, but shorter than full examples.

Example idea to cover:

• Setting up a custom time line
• Setting up a blueprint
• Simple 2D plots
• …

The cookbook should have the same code in all languages.

[teh-cmc]

I think we should only have two kinds of examples (not to be confused with categories): full fledged demos (most of what we have in examples/ today, with the exception of stuff like multithreading and such, as well as everything we have in external repos) and recipes / cookbook-style examples (I count all archetype snippets as such, as well as a few of the smaller things in the examples/ folder).

It would be longer than archetype snippets, but shorter than full examples.

Imo the length of an example isn't really that important when it comes to determining its kind (of course a recipe shouldn't be 5000 lines of code scattered across 10 files -- common sense still applies).

An example should either demonstrate how the product behaves in a real-world scenario (it's a demo), or it should show how to use the product to achieve one very specific thing (it's a recipe). That doesn't mean a recipe cannot get complex/lengthy -- sometimes the one single thing you want to achieve does in fact require a lot of code to achieve, and that's fine.

Now, as for categories, both demos and recipes can have an arbitrary amount of categories.

---

As a real-world example, I will once again have to bring up the Bevy examples (shocker!).

Bevy basically has these same two kinds of examples: recipes (which can get quite complex) and full-fledged demos (games, in this instance).

And it is the best project cookbook I've ever used by a long mile.

[jleibs]

The introduction of dataframe APIs is likely to place a heavy documentation load that would be very well served by cook-book style documentation.

This is particularly notable as likely motivating code snippets for various common use-cases mirrored across several frameworks:

• Arrow
• Polars
• Pandas
• Datafusion
• DuckDB

In all of these cases it is code native to those libraries and so we are documenting ways to use those libraries with Rerun data, which is a topic that cannot be easily documented with our own docs framework.

An additional request for implementing this is that these snippets are likely to surface out of support requests. As such being able to easily update the cookbook without a doc release cycle would be extremely valuable.

[abey79]

I have a proposal to go about this:

1. We create a new (public) repo rerun-io/cookbook.
2. That repository is just a collection of markdown files in folders.
3. Landing page has a new "Cookbook" section whose content mirrors the hierarchy and content of the cookbook repo. Pushing to cookbook's main triggers a landing page deployment.

Pros:

• Updating the cookbook is a simple PR with no other schenaniganeries.
• The cookbook content is open to public contribution in a very accessible way. (Bells and whistles includes acknowledging contributors on the rendered page, to further promote contribution).

Cons:

• None :)

Inspiration: the TIL section of Simon Willison's blog.

• Repo: https://github.com/simonw/til
• Deployed: https://til.simonwillison.net

[nikolausWest]

Cons with the rerun-io/cookbook repo approach:

• Version mismatches:
  • How should someone add a cookbook for a coming Rerun version that uses features that aren't yet supported?
  • How are we keeping track of version requirements for the entries? Enforcing they all work on latest release? Separate versions per entry? How do we run CI on these in that case? If no CI, do we just let these go stale and still have them on our docs page?
• Community vs official:
  • If we actually render them on our docs we should probably have some way of separating community vs official cookbooks. In general we need to deal with the level of polish and "does thing in the right way"-ness we want to enforce on these.

[abey79]

How should someone add a cookbook for a coming Rerun version that uses features that aren't yet supported?

Maybe just a release branch on rerun-io/cookbook that we merge just after rerun release?

How are we keeping track of version requirements for the entries? Enforcing they all work on latest release? Separate versions per entry? How do we run CI on these in that case? If no CI, do we just let these go stale and still have them on our docs page?

Meta-answer: the spirit of the cookbook is to not let "perfect" get in the way of "good" (and "done").

Ensuring code doesn't rot is a valid concern. Ideally we'd have some variant of the snippet system, but that is local to the recipe in question and doest required messing with 3 config files in 2 different places. Fluidity is key here imo.

If we actually render them on our docs we should probably have some way of separating community vs official cookbooks. In general we need to deal with the level of polish and "does thing in the right way"-ness we want to enforce on these.

I'd expect the cookbook to undergo a standard PR reviews, so community contributions would be just as good an ours. Specifically, this would not be a wiki-like thing that anyone (or anyone with some privilege) could edit at will.

[emilk]

Let's start simple:

• Add a Cookbook header to rerun.io/docs
• Just write markdown. Low bar: no code testing etc
• Maybe add a GitHub label to tell CI to cherry-pick a PR into doc-latest

Once we have 50 cookbook recipes, we can think about engineering this differently

[teh-cmc]

That is super neat and would fit perfectly into that: https://discord.com/channels/1062300748202921994/1075873257124810852/1301647484891955241

---

@jleibs wrote:

Regarding the height map, the depth image is an interesting idea -- it's not exactly designed for that and I think the perspective projection might not be exactly what you want, but I'd be interested to hear if you're able to make it work.

The other way we've seen folks handle this is with an array of Boxes3D.

Here's a python snippet:

import rerun as rr

import numpy as np

rr.init("rerun_example_height_map", spawn=True)

height_map = np.random.rand(10, 10) * 10

# create the coordinate grid
x = np.linspace(0, 10, 10)
y = np.linspace(0, 10, 10)
X, Y = np.meshgrid(x, y)

# Offset the centers by half the height
centers = np.stack([X.flatten(), Y.flatten(), height_map.flatten() / 2.0]).transpose()

half_sizes = np.ones((len(centers), 3)) * 0.5
half_sizes[:, 2] = height_map.flatten() / 2


rr.log(
    "height_map_3d",
    rr.Boxes3D(
        centers=centers,
        half_sizes=half_sizes,
        fill_mode=rr.components.FillMode.Solid,
    ),
    rr.AnyValues(value=height_map.flatten()),
)