Docs: "How-to: reuse blueprints across languages" (#7886)

By popular demand.

* Fixes #7858
* DNM: requires #7882

Author: teh-cmc

docs/content/concepts/blueprint.md

@@ -1,5 +1,5 @@
 ---
-title: Blueprint
+title: Blueprints
 order: 600
 ---
 

docs/content/howto/visualization/configure-viewer-through-code.md

@@ -1,5 +1,5 @@
 ---
-title: Configure the Viewer through code
+title: Configure the Viewer through code (Blueprints)
 order: 100
 ---
 

docs/content/howto/visualization/reuse-blueprints.md

@@ -0,0 +1,44 @@
+---
+title: Re-use blueprints across sessions and SDKs
+order: 150
+---
+
+While the [blueprint APIs](configure-viewer-through-code) are currently only available through [🐍 Python](https://ref.rerun.io/docs/python/stable/common/blueprint_apis/), blueprints can be saved to file and then re-logged as needed from any language our SDKs support.
+
+This enables you to re-use your saved blueprints both from any language we support as well as across different recordings that share a similar-enough structure, and makes it possible to share those blueprints with other users.
+
+For this you'll need to 1) create a blueprint file and B) _import_ that file when needed.
+
+
+## Creating a blueprint file
+
+Blueprint files (`.rbl`, by convention) can currently be created in two ways.
+
+One is to use the Rerun viewer to interactively build the blueprint you want (e.g. by moving panels around, changing view settings, etc), and then using `Menu > Save blueprint` (or the equivalent palette command) to save the blueprint as a file.
+
+The other is to use the [🐍 Python blueprint API](https://ref.rerun.io/docs/python/stable/common/blueprint_apis/) to programmatically build the blueprint, and then use the [`Blueprint.save`](https://ref.rerun.io/docs/python/0.19.0/common/blueprint_apis/#rerun.blueprint.Blueprint.save) method to save it as a file:
+
+snippet: tutorials/visualization/save_blueprint
+
+
+## (Re)Using a blueprint file
+
+There are two ways to re-use a blueprint file.
+
+The interactive way is to import the blueprint file directly into the Rerun viewer, using either `Menu > Import…` (or the equivalent palette command) or simply by drag-and-dropping the blueprint file into your recording.
+
+The programmatic way works by calling `log_file_from_path`:
+* [🐍 Python `log_file_from_path`](https://ref.rerun.io/docs/python/stable/common/logging_functions/#rerun.log_file_from_path)
+* [🦀 Rust `log_file_from_path`](https://docs.rs/rerun/latest/rerun/struct.RecordingStream.html#method.log_file_from_path)
+* [🌊 C++ `log_file_from_path`](https://ref.rerun.io/docs/cpp/stable/classrerun_1_1RecordingStream.html#a20798d7ea74cce5c8174e5cacd0a2c47)
+
+This method allows you to log any file that contains data that Rerun understands (in this case, blueprint data) as part of your current recording:
+
+snippet: tutorials/visualization/load_blueprint
+
+
+## Limitation: dynamic blueprints
+
+Sometimes, you might need your blueprint to dynamically react to the data you receive at runtime (e.g. you want to create one view per anomaly detected, and there is no way of knowing how many anomalies you're going to detect until the program actually runs).
+
+The only way to deal with these situations today is to use the [🐍 Python](https://ref.rerun.io/docs/python/stable/common/blueprint_apis/) API.

docs/content/reference/dataframes.md

@@ -48,7 +48,7 @@ snippet: reference/dataframe_view_query
 
 #### Aside: re-using blueprint files from other SDKs
 
-While the blueprint APIs are currently only available in Python, blueprints can be saved and re-logged as needed from any language our SDKs support.
+While the blueprint APIs are currently only available through Python, blueprints can be saved and re-logged as needed from any language our SDKs support.
 
 First, save the blueprint to a file (`.rbl` by convention) using either the viewer (`Menu > Save blueprint`) or the python API:
 
@@ -64,6 +64,8 @@ Check out the blueprint API and `log_file_from_path` references to learn more:
 * [🦀 Rust `log_file_from_path`](https://docs.rs/rerun/latest/rerun/struct.RecordingStream.html#method.log_file_from_path)
 * [🌊 C++ `log_file_from_path`](https://ref.rerun.io/docs/cpp/stable/classrerun_1_1RecordingStream.html#a20798d7ea74cce5c8174e5cacd0a2c47)
 
+You can learn more in our [dedicated page about blueprint re-use](../howto/visualization/reuse-blueprints).
+
 
 ### Setting up dataframe view manually in the UI
 

docs/snippets/all/tutorials/visualization/load_blueprint.py

@@ -0,0 +1,12 @@
+"""Demonstrates how to programmatically re-use a blueprint stored in a file."""
+
+import sys
+
+import rerun as rr
+
+path_to_rbl = sys.argv[1]
+
+rr.init("rerun_example_reuse_blueprint_file", spawn=True)
+rr.log_file_from_path(path_to_rbl)
+
+# … log some data as usual …

docs/snippets/all/tutorials/visualization/save_blueprint.py

@@ -0,0 +1,23 @@
+"""Craft an example blueprint with the python API and save it to a file for future use."""
+
+import sys
+
+import rerun.blueprint as rrb
+
+path_to_rbl = sys.argv[1]
+
+rrb.Blueprint(
+    rrb.Horizontal(
+        rrb.Grid(
+            rrb.BarChartView(name="Bar Chart", origin="/bar_chart"),
+            rrb.TimeSeriesView(
+                name="Curves",
+                origin="/curves",
+            ),
+        ),
+        rrb.TextDocumentView(name="Description", origin="/description"),
+        column_shares=[3, 1],
+    ),
+    rrb.SelectionPanel(state="collapsed"),
+    rrb.TimePanel(state="collapsed"),
+).save("your_blueprint_name", path_to_rbl)