wip

crates/build/re_types_builder/src/codegen/common.rs

@@ -319,13 +319,40 @@ pub fn collect_snippets_for_api_docs<'a>(
             }
         };
         let mut content = content
-            .split('\n')
-            .map(String::from)
-            .skip_while(|line| line.starts_with("//") || line.starts_with(r#"""""#)) // Skip leading comments.
+            .lines()
+            .map(ToOwned::to_owned)
+            .skip_while(|line| line.starts_with("//")) // Skip leading comments.
             .skip_while(|line| line.trim().is_empty()) // Strip leading empty lines.
             .collect_vec();
 
+        // Remove multi-line Python docstrings, otherwise we can't embed this.
+        if content
+            .first()
+            .map_or(false, |line| line.trim() == "\"\"\"")
+        {
+            if let Some((i, _)) = content
+                .iter()
+                .skip(1)
+                .find_position(|line| line.trim() == "\"\"\"")
+            {
+                content = content.into_iter().skip(i + 2).collect();
+            }
+        }
+
+        // Remove one-line Python docstrings, otherwise we can't embed this.
+        if let Some(first_line) = content.first() {
+            if first_line.starts_with("\"\"\"")
+                && first_line.ends_with("\"\"\"")
+                && first_line.len() > 6
+            {
+                content.remove(0);
+            }
+        }
+
         // trim trailing blank lines
+        while content.first().is_some_and(is_blank) {
+            content.remove(0);
+        }
         while content.last().is_some_and(is_blank) {
             content.pop();
         }

crates/build/re_types_builder/src/codegen/docs/snippets_ref.rs

@@ -2,12 +2,13 @@
 
 use std::{
     cmp::Ordering,
-    collections::{BTreeMap, BTreeSet},
+    collections::{BTreeMap, BTreeSet, HashMap},
     path::PathBuf,
 };
 
 use anyhow::Context;
 use camino::{Utf8Path, Utf8PathBuf};
+use itertools::Itertools as _;
 
 use crate::{CodeGenerator, GeneratedFiles, Object, ObjectKind, Objects, Reporter};
 
@@ -26,7 +27,7 @@ struct SnippetsRef {
     components: OptOut,
 
     // <feature_name, vec<snippet_name_qualified>>
-    features: BTreeMap<String, Vec<String>>,
+    features: Vec<(String, Vec<String>)>,
 }
 
 #[derive(Debug, serde::Deserialize)]
@@ -50,7 +51,6 @@ struct Snippet<'o> {
     description: Option<String>,
     contents: String,
 
-    features: BTreeSet<String>,
     archetypes: BTreeSet<&'o Object>,
     components: BTreeSet<&'o Object>,
     archetypes_blueprint: BTreeSet<&'o Object>,
@@ -61,7 +61,8 @@ struct Snippet<'o> {
 /// Maps objects (archetypes, components, etc) back to snippets.
 #[derive(Default, Debug)]
 struct Snippets<'o> {
-    per_feature: BTreeMap<String, Vec<Snippet<'o>>>,
+    per_name_qualified: HashMap<String, Snippet<'o>>,
+    per_feature: Vec<(String, Vec<Snippet<'o>>)>,
     per_archetype: BTreeMap<&'o Object, Vec<Snippet<'o>>>,
     per_archetype_blueprint: BTreeMap<&'o Object, Vec<Snippet<'o>>>,
     per_view: BTreeMap<&'o Object, Vec<Snippet<'o>>>,
@@ -70,18 +71,15 @@ struct Snippets<'o> {
 impl<'o> Snippets<'o> {
     fn merge_extend(&mut self, rhs: Self) {
         let Self {
+            per_name_qualified,
             per_feature,
             per_archetype,
             per_archetype_blueprint,
             per_view,
         } = self;
 
-        for (feature, snippets) in rhs.per_feature {
-            per_feature
-                .entry(feature.clone())
-                .or_default()
-                .extend(snippets);
-        }
+        per_name_qualified.extend(rhs.per_name_qualified);
+        per_feature.extend(rhs.per_feature);
 
         let merge_extend = |a: &mut BTreeMap<&'o Object, Vec<Snippet<'o>>>, b| {
             for (obj, snippets) in b {
@@ -274,19 +272,7 @@ impl SnippetsRefCodeGenerator {
             .per_feature
             .iter()
             .flat_map(|(feature, snippets)| {
-                let mut snippets = snippets.clone();
-                // NOTE: Gotta sort twice to make sure it stays stable after the second one.
-                snippets.sort_by(|a, b| a.name_qualified.cmp(&b.name_qualified));
-                snippets.sort_by(|a, b| {
-                    if a.name.contains(feature) {
-                        // Snippets that contain the feature in question in their name should
-                        // bubble up to the top.
-                        Ordering::Less
-                    } else {
-                        a.name.cmp(&b.name)
-                    }
-                });
-                snippets.into_iter().map(move |snippet| (feature, snippet))
+                snippets.iter().map(move |snippet| (feature, snippet))
             })
             .map(|(feature, snippet)| {
                 let snippet_name = &snippet.name;
@@ -356,7 +342,7 @@ Use it to quickly find copy-pastable snippets of code for any Rerun feature you'
 ## Features
 
 | Feature | Example | Description | Python | Rust | C+⁠+ |
-| ------- | ------- | ----------- | ------ | ---- | --- |
+| ------- | ------- | ----------- | :----: | :--: | :-------: |
 {per_feature_table}
 
 
@@ -368,7 +354,7 @@ Use it to quickly find copy-pastable snippets of code for any Rerun feature you'
 _All snippets, organized by the [`Archetype`](https://rerun.io/docs/reference/types/archetypes)(s) they use._
 
 | Archetype | Snippet | Description | Python | Rust | C+⁠+ |
-| --------- | ------- | ----------- | ------ | ---- | --- |
+| --------- | ------- | ----------- | :----: | :--: | :-------: |
 {per_archetype_table}
 
 
@@ -377,7 +363,7 @@ _All snippets, organized by the [`Archetype`](https://rerun.io/docs/reference/ty
 _All snippets, organized by the [`View`](https://rerun.io/docs/reference/types/views)(s) they use._
 
 | Component | Snippet | Description | Python | Rust | C+⁠+ |
-| --------- | ------- | ----------- | ------ | ---- | --- |
+| --------- | ------- | ----------- | :----: | :--: | :-------: |
 {per_view_table}
 
 
@@ -386,7 +372,7 @@ _All snippets, organized by the [`View`](https://rerun.io/docs/reference/types/v
 _All snippets, organized by the blueprint-related [`Archetype`](https://rerun.io/docs/reference/types/archetypes)(s) they use._
 
 | Archetype | Snippet | Description | Python | Rust | C+⁠+ |
-| --------- | ------- | ----------- | ------ | ---- | --- |
+| --------- | ------- | ----------- | :----: | :--: | :-------: |
 {per_archetype_blueprint_table}
 "
         );
@@ -432,25 +418,30 @@ fn collect_snippets_recursively<'o>(
         }
 
         let contents = std::fs::read_to_string(&path)?;
-        let description = contents.lines().take(1).next().and_then(|s| {
-            s.contains("\"\"\"")
-                .then(|| s.replace("\"\"\"", "").trim_end_matches('.').to_owned())
-        });
+
+        let description = {
+            let lines = contents
+                .lines()
+                .skip_while(|line| line.trim().is_empty()) // Strip leading empty lines.
+                .collect_vec();
+            if lines.first().map_or(false, |line| line.trim() == "\"\"\"") {
+                // Multi-line Python docstrings.
+                lines.iter().skip(1).take(1).next()
+            } else {
+                // Single-line Python docstrings.
+                lines.iter().take(1).next().filter(|s| s.contains("\"\"\""))
+            }
+            .map(|s| s.replace("\"\"\"", "").trim_end_matches('.').to_owned())
+        };
 
         // All archetypes, components, etc that this snippet refers to.
-        let mut features = BTreeSet::default();
         let mut archetypes = BTreeSet::default();
         let mut components = BTreeSet::default();
         let mut archetypes_blueprint = BTreeSet::default();
         let mut components_blueprint = BTreeSet::default();
         let mut views = BTreeSet::default();
 
         // Fill the sets by grepping into the snippet's contents.
-        for (feature, snippets) in &config.snippets_ref.features {
-            if snippets.contains(&name_qualified) {
-                features.insert(feature.clone());
-            }
-        }
         for (objs, set) in [
             (&known_objects.archetypes, &mut archetypes),
             (&known_objects.components, &mut components),
@@ -488,22 +479,18 @@ fn collect_snippets_recursively<'o>(
             rust,
             cpp,
 
-            features,
             archetypes,
             components,
             archetypes_blueprint,
             components_blueprint,
             views,
         };
 
+        snippets
+            .per_name_qualified
+            .insert(snippet.name_qualified.clone(), snippet.clone());
+
         // Fill the reverse indices.
-        for feature in &snippet.features {
-            snippets
-                .per_feature
-                .entry(feature.clone())
-                .or_default()
-                .push(snippet.clone());
-        }
         for (objs, index) in [
             (&snippet.archetypes, &mut snippets.per_archetype),
             (&snippet.views, &mut snippets.per_view),
@@ -518,6 +505,22 @@ fn collect_snippets_recursively<'o>(
         }
     }
 
+    {
+        let mut per_feature = Vec::new();
+        for (feature, names_qualified) in &config.snippets_ref.features {
+            per_feature.push((
+                feature.clone(),
+                names_qualified
+                    .iter()
+                    .filter_map(|name_qualified| {
+                        snippets.per_name_qualified.get(name_qualified).cloned()
+                    })
+                    .collect_vec(),
+            ));
+        }
+        snippets.per_feature = per_feature;
+    }
+
     Ok(snippets)
 }
 

crates/build/re_types_builder/src/codegen/python/mod.rs

@@ -1177,24 +1177,7 @@ fn quote_examples(examples: Vec<Example<'_>>, lines: &mut Vec<String>) {
             ..
         } = &example.base;
 
-        let mut example_lines = example.lines.clone();
-
-        if let Some(first_line) = example_lines.first() {
-            if first_line.starts_with("\"\"\"")
-                && first_line.ends_with("\"\"\"")
-                && first_line.len() > 6
-            {
-                // Remove one-line docstring, otherwise we can't embed this.
-                example_lines.remove(0);
-            }
-        }
-
-        // Remove leading blank lines:
-        while example_lines.first() == Some(&String::default()) {
-            example_lines.remove(0);
-        }
-
-        for line in &example_lines {
+        for line in &example.lines {
             assert!(
                 !line.contains("```"),
                 "Example {path:?} contains ``` in it, so we can't embed it in the Python API docs."
@@ -1211,7 +1194,7 @@ fn quote_examples(examples: Vec<Example<'_>>, lines: &mut Vec<String>) {
             lines.push(format!("### `{name}`:"));
         }
         lines.push("```python".into());
-        lines.extend(example_lines.into_iter());
+        lines.extend(example.lines.into_iter());
         lines.push("```".into());
         if let Some(image) = &image {
             lines.extend(

crates/store/re_types/definitions/rerun/archetypes/image.fbs

@@ -20,9 +20,11 @@ namespace rerun.archetypes;
 /// \cpp data can be passed in without a copy from raw pointers or by reference from `std::vector`/`std::array`/c-arrays.
 /// \cpp If needed, this "borrow-behavior" can be extended by defining your own `rerun::CollectionAdapter`.
 ///
-/// \example archetypes/image_simple image="https://static.rerun.io/image_simple/06ba7f8582acc1ffb42a7fd0006fad7816f3e4e4/1200w.png"
-/// \example archetypes/image_formats title="Logging images with various formats" image="https://static.rerun.io/image_formats/7b8a162fcfd266f303980439beea997dc8544c24/full.png"
-/// \example archetypes/image_send_columns !api title="Image from file, PIL & OpenCV" image="https://static.rerun.io/image_advanced/81fc8a255488615510790ee41be314e054978d51/full.png"
+/// \example archetypes/image_simple !api image="https://static.rerun.io/image_simple/06ba7f8582acc1ffb42a7fd0006fad7816f3e4e4/1200w.png"
+/// \example archetypes/image_formats !api title="Logging images with various formats" image="https://static.rerun.io/image_formats/182a233fb4d0680eb31912a82f328ddaaa66324e/1200w.png"
+/// \example archetypes/image_advanced !api title="Image from file, PIL & OpenCV" image="https://static.rerun.io/image_advanced/7ea3e3876858879bf16d6efe6de313f7b2403881/1200w.png"
+/// \example archetypes/image_row_updates title="Update an image over time" image="https://static.rerun.io/image_column_updates/8edcdc512f7b97402f03c24d7dcbe01b3651f86d/1200w.png"
+/// \example archetypes/image_column_updates title="Update an image over time, in a single operation" image="https://static.rerun.io/image_column_updates/8edcdc512f7b97402f03c24d7dcbe01b3651f86d/1200w.png"
 table Image (
   "attr.rust.derive": "PartialEq",
   "attr.cpp.no_field_ctors",

crates/store/re_types/definitions/rerun/archetypes/mesh3d.fbs

@@ -10,8 +10,8 @@ namespace rerun.archetypes;
 /// an instance of the mesh will be drawn for each transform.
 ///
 /// \example archetypes/mesh3d_indexed title="Simple indexed 3D mesh" image="https://static.rerun.io/mesh3d_indexed/57c70dc992e6dc0bd9c5222ca084f5b6240cea75/1200w.png"
-/// \example archetypes/mesh3d_partial_updates !api title="3D mesh with partial updates" image="https://static.rerun.io/mesh3d_partial_updates/7de33d26220585691a403098c953cd46f94c3262/1200w.png"
 /// \example archetypes/mesh3d_instancing title="3D mesh with instancing" image="https://static.rerun.io/mesh3d_leaf_transforms3d/c2d0ee033129da53168f5705625a9b033f3a3d61/1200w.png"
+/// \example archetypes/mesh3d_partial_updates title="Update specific parts of a 3D mesh over time" image="https://static.rerun.io/mesh3d_partial_updates/79b8a83294ef2c1eb7f9ae7dea7267a17da464ae/1200w.png"
 table Mesh3D (
   "attr.rust.derive": "PartialEq",
   "attr.docs.category": "Spatial 3D",

crates/store/re_types/definitions/rerun/archetypes/points3d.fbs

@@ -4,10 +4,12 @@ namespace rerun.archetypes;
 
 /// A 3D point cloud with positions and optional colors, radii, labels, etc.
 ///
-/// \example archetypes/points3d_simple !api title="Simple 3D points" image="https://static.rerun.io/point3d_simple/32fb3e9b65bea8bd7ffff95ad839f2f8a157a933/1200w.png"
-/// \example archetypes/points3d_random title="Randomly distributed 3D points with varying color and radius" image="https://static.rerun.io/point3d_random/7e94e1806d2c381943748abbb3bedb68d564de24/1200w.png"
-/// \example archetypes/points3d_ui_radius title="Log points with radii given in UI points" image="https://static.rerun.io/point3d_ui_radius/e051a65b4317438bcaea8d0eee016ac9460b5336/1200w.png"
-/// \example archetypes/points3d_send_columns title="Send several point clouds with varying point count over time in a single call" image="https://static.rerun.io/points3d_send_columns/633b524a2ee439b0e3afc3f894f4927ce938a3ec/1200w.png"
+/// \example archetypes/points3d_simple title="Simple 3D points" image="https://static.rerun.io/point3d_simple/32fb3e9b65bea8bd7ffff95ad839f2f8a157a933/1200w.png"
+/// \example archetypes/points3d_random !api title="Randomly distributed 3D points with varying color and radius" image="https://static.rerun.io/point3d_random/7e94e1806d2c381943748abbb3bedb68d564de24/1200w.png"
+/// \example archetypes/points3d_ui_radius !api title="Log points with radii given in UI points" image="https://static.rerun.io/point3d_ui_radius/e051a65b4317438bcaea8d0eee016ac9460b5336/1200w.png"
+/// \example archetypes/points3d_row_updates title="Update a point cloud over time" image="https://static.rerun.io/points3d_row_updates/fba056871b1ec3fc6978ab605d9a63e44ef1f6de/1200w.png"
+/// \example archetypes/points3d_column_updates title="Update a point cloud over time, in a single operation" image="https://static.rerun.io/points3d_row_updates/fba056871b1ec3fc6978ab605d9a63e44ef1f6de/1200w.png"
+/// \example archetypes/points3d_partial_updates title="Update specific properties of a point cloud over time" image="https://static.rerun.io/points3d_partial_updates/d8bec9c3388d2bd0fe59dff01ab8cde0bdda135e/1200w.png"
 table Points3D (
   "attr.rust.derive": "PartialEq",
   "attr.docs.category": "Spatial 3D",

crates/store/re_types/definitions/rerun/archetypes/scalar.fbs

@@ -12,9 +12,10 @@ namespace rerun.archetypes;
 /// this by logging both archetypes to the same path, or alternatively configuring
 /// the plot-specific archetypes through the blueprint.
 ///
-/// \example archetypes/scalar_simple title="Simple line plot" image="https://static.rerun.io/scalar_simple/8bcc92f56268739f8cd24d60d1fe72a655f62a46/1200w.png"
+/// \example archetypes/scalar_simple !api title="Simple line plot" image="https://static.rerun.io/scalar_simple/8bcc92f56268739f8cd24d60d1fe72a655f62a46/1200w.png"
 /// \example archetypes/scalar_multiple_plots !api title="Multiple time series plots" image="https://static.rerun.io/scalar_multiple/15845c2a348f875248fbd694e03eabd922741c4c/1200w.png"
-/// \example archetypes/scalar_send_columns title="Multiple scalars in a single `send_columns` call" image="https://static.rerun.io/scalar_send_columns/b4bf172256f521f4851dfec5c2c6e3143f5d6923/1200w.png"
+/// \example archetypes/scalar_row_updates title="Update a scalar over time" image="https://static.rerun.io/transform3d_column_updates/2b7ccfd29349b2b107fcf7eb8a1291a92cf1cafc/1200w.png"
+/// \example archetypes/scalar_column_updates title="Update a scalar over time, in a single operation" image="https://static.rerun.io/transform3d_column_updates/2b7ccfd29349b2b107fcf7eb8a1291a92cf1cafc/1200w.png"
 table Scalar (
   "attr.rust.derive": "PartialEq",
   "attr.docs.category": "Plotting",

crates/store/re_types/definitions/rerun/archetypes/transform3d.fbs

@@ -1,6 +1,5 @@
 namespace rerun.archetypes;
 
-
 /// A transform between two 3D spaces, i.e. a pose.
 ///
 /// From the point of view of the entity's coordinate system,
@@ -16,6 +15,9 @@ namespace rerun.archetypes;
 ///
 /// \example archetypes/transform3d_simple title="Variety of 3D transforms" image="https://static.rerun.io/transform3d_simple/141368b07360ce3fcb1553079258ae3f42bdb9ac/1200w.png"
 /// \example archetypes/transform3d_hierarchy title="Transform hierarchy" image="https://static.rerun.io/transform_hierarchy/cb7be7a5a31fcb2efc02ba38e434849248f87554/1200w.png"
+/// \example archetypes/transform3d_row_updates title="Update a transform over time" image="https://static.rerun.io/transform3d_column_updates/80634e1c7c7a505387e975f25ea8b6bc1d4eb9db/1200w.png"
+/// \example archetypes/transform3d_column_updates title="Update a transform over time, in a single operation" image="https://static.rerun.io/transform3d_column_updates/80634e1c7c7a505387e975f25ea8b6bc1d4eb9db/1200w.png"
+/// \example archetypes/transform3d_partial_updates title="Update specific properties of a transform over time" image="https://static.rerun.io/transform3d_partial_updates/11815bebc69ae400847896372b496cdd3e9b19fb/1200w.png"
 table Transform3D (
   "attr.docs.category": "Spatial 3D",
   "attr.docs.view_types": "Spatial3DView, Spatial2DView: if logged above active projection",