Shared recordings 3: add how-to guide (#4385)

What the title says.

Rendered:

![image](https://github.com/rerun-io/rerun/assets/2910679/1734fdcf-7bc4-4521-91f8-f906610cf974)


---

Part of a PR series to fix #4055 once and for all:
- #4383
- #4384
- #4385

docs/code-examples/custom-recording-id/example.cpp

@@ -0,0 +1 @@
+const auto rec = rerun::RecordingStream("rerun_example_shared_recording", "my_shared_recording");

docs/code-examples/custom-recording-id/example.py

@@ -0,0 +1,3 @@
+import rerun as rr
+
+rr.init("rerun_example_shared_recording", recording_id="my_shared_recording")

docs/code-examples/custom-recording-id/example.rs

@@ -0,0 +1,2 @@
+rerun::RecordingStreamBuilder::new("rerun_example_shared_recording")
+    .recording_id("my_shared_recording")

docs/content/howto/notebook.md

@@ -1,6 +1,6 @@
 ---
 title: Using Rerun with Notebooks
-order: 1
+order: 3
 description: How to embed Rerun in notebooks like Jupyter or Colab
 ---
 

docs/content/howto/ros2-nav-turtlebot.md

@@ -1,6 +1,6 @@
 ---
 title: Using Rerun with ROS 2
-order: 2
+order: 4
 ogImageUrl: /docs-media/og-howto-ros.jpg
 description: Rerun does not yet have native ROS support, but many of the concepts in ROS and Rerun line up fairly well. In this guide, you will learn how to write a simple ROS 2 python node that subscribes to some common ROS topics and logs them to Rerun.
 ---

docs/content/howto/shared-recordings.md

@@ -0,0 +1,38 @@
+---
+title: Share a recording across multiple processes
+order: 2
+---
+
+A common need is to log data from multiple processes  and then visualize all of that data as part of a single shared recording.
+
+Rerun has the notion of a [Recording ID](../concepts/apps-and-recordings.md) for that: any recorded datasets that share the same Recording ID will be visualized as one shared dataset.
+
+The data can be logged from any number of processes, whether they run on the same machine or not, or implemented in different programming languages.
+All that matter is that they share the same Recording ID.
+
+By default, Rerun generates a random Recording ID everytime you start a new logging session, but you can override that behavior, e.g.:
+
+code-example: custom-recording-id
+
+It's up to you to decide where each recording ends up:
+- all processes could stream their share of the data in real-time to a Rerun Viewer,
+- or maybe they all write to their own file on disk that are later loaded in a viewer,
+- or some other combination of the above.
+
+Here's a simple example of such a workflow:
+```python
+# Process 1 logs some spheres to a recording file.
+./app1.py  # rr.init(recording_id='my_shared_recording', rr.save('/tmp/recording1.rrd')
+
+# Process 2 logs some cubes to another recording file.
+./app2.py  # rr.init(recording_id='my_shared_recording', rr.save('/tmp/recording2.rrd')
+
+# Visualize a 3D scene with both spheres and cubes.
+rerun /tmp/recording*.rrd  # they share the same Recording ID!
+```
+
+For more information, check out our [dedicated example](https://github.com/rerun-io/rerun/tree/main/examples/python/shared_recording?speculative-link).
+
+### Caveats
+
+We do not yet provide a way to merge [multiple recording files](https://github.com/rerun-io/rerun/issues/4057) into a single one directly from the CLI, although you can load all of them in the Rerun Viewer first and then use the save feature ([which has its own issues](https://github.com/rerun-io/rerun/issues/3091)).

examples/python/requirements.txt

@@ -24,6 +24,7 @@
 -r rgbd/requirements.txt
 -r ros_node/requirements.txt
 -r segment_anything_model/requirements.txt
+-r shared_recording/requirements.txt
 -r signed_distance_fields/requirements.txt
 -r structure_from_motion/requirements.txt
 -r template/requirements.txt

examples/python/shared_recording/README.md

@@ -0,0 +1,21 @@
+---
+title: Shared Recording
+python: https://github.com/rerun-io/rerun/tree/latest/examples/python/shared_recording/main.py?speculative-link
+rust: https://github.com/rerun-io/rerun/tree/latest/examples/rust/shared_recording/src/main.rs?speculative-link
+cpp: https://github.com/rerun-io/rerun/tree/latest/examples/cpp/shared_recording/main.cpp?speculative-link
+---
+
+<picture>
+  <img src="https://static.rerun.io/shared_recording/c3da85f1d4c158b8c7afb6bd3278db000b58049d/full.png" alt="">
+  <source media="(max-width: 480px)" srcset="https://static.rerun.io/shared_recording/c3da85f1d4c158b8c7afb6bd3278db000b58049d/480w.png">
+  <source media="(max-width: 768px)" srcset="https://static.rerun.io/shared_recording/c3da85f1d4c158b8c7afb6bd3278db000b58049d/768w.png">
+  <source media="(max-width: 1024px)" srcset="https://static.rerun.io/shared_recording/c3da85f1d4c158b8c7afb6bd3278db000b58049d/1024w.png">
+  <source media="(max-width: 1200px)" srcset="https://static.rerun.io/shared_recording/c3da85f1d4c158b8c7afb6bd3278db000b58049d/1200w.png">
+</picture>
+
+This example demonstrates how to use `RecordingId`s to create a single shared recording across multiple processes.
+
+Run the following multiple times, and you'll see that each invocation adds data to the existing recording rather than creating a new one:
+```bash
+python examples/python/shared_recording/main.py
+```

examples/python/shared_recording/main.py

@@ -0,0 +1,17 @@
+#!/usr/bin/env python3
+"""Demonstrates how to use `RecordingId`s to build a single recording from multiple processes."""
+from __future__ import annotations
+
+import os
+import sys
+
+import rerun as rr  # pip install rerun-sdk
+
+# sanity-check since all other example scripts take arguments:
+assert len(sys.argv) == 1, f"{sys.argv[0]} does not take any arguments"
+
+rr.init("rerun_example_shared_recording", recording_id="my_shared_recording", spawn=True)
+
+rr.log("updates", rr.TextLog(f"hello from {os.getpid()}"))
+
+print("Run me again to append more data to the recording!")

examples/python/shared_recording/requirements.txt

@@ -0,0 +1 @@
+rerun-sdk