Docs codegen (#3445)

### What Closes #2775 - [x] Add docs as a new "language" in codegen - [x] Replace old docs with new ones - [x] Minor output polish work - [x] Components and APIs section should say "Required Components" instead of just "Required" (for all kinds) - [x] Use actual headings for example titles - [x] Use images even in `.rs`/`.py` files Follow-up work: #3503 ### Checklist * [x] I have read and agree to [Contributor Guide](https://github.com/rerun-io/rerun/blob/main/CONTRIBUTING.md) and the [Code of Conduct](https://github.com/rerun-io/rerun/blob/main/CODE_OF_CONDUCT.md) * [x] I've included a screenshot or gif (if applicable) * [x] I have tested [demo.rerun.io](https://demo.rerun.io/pr/3445) (if applicable) - [PR Build Summary](https://build.rerun.io/pr/3445) - [Docs preview](https://rerun.io/preview/3bd57dabdaea4a24bd6c67301e321734fadee864/docs)  - [Examples preview](https://rerun.io/preview/3bd57dabdaea4a24bd6c67301e321734fadee864/examples)  - [Recent benchmark results](https://ref.rerun.io/dev/bench/) - [Wasm size tracking](https://ref.rerun.io/dev/sizes/) --------- Co-authored-by: Emil Ernerfeldt <[email protected]>
rerun-io · Sep 28, 2023 · 65bad7e · 65bad7e
1 parent c43a0f3
commit 65bad7e
Show file tree

Hide file tree

Showing 108 changed files with 2,190 additions and 645 deletions.
diff --git a/crates/re_types/build.rs b/crates/re_types/build.rs
@@ -13,11 +13,24 @@ const SOURCE_HASH_PATH: &str = "./source_hash.txt";
 const DEFINITIONS_DIR_PATH: &str = "./definitions";
 const ENTRYPOINT_PATH: &str = "./definitions/rerun/archetypes.fbs";
 const DOC_EXAMPLES_DIR_PATH: &str = "../../docs/code-examples";
+const DOC_CONTENT_DIR_PATH: &str = "../../docs/content/reference/data_types";
 const CPP_OUTPUT_DIR_PATH: &str = "../../rerun_cpp";
 const RUST_OUTPUT_DIR_PATH: &str = ".";
 const PYTHON_OUTPUT_DIR_PATH: &str = "../../rerun_py/rerun_sdk/rerun";
 const PYTHON_TESTING_OUTPUT_DIR_PATH: &str = "../../rerun_py/tests/test_types";
 
+/// This uses [`rayon::scope`] to spawn all closures as tasks
+/// running in parallel. It blocks until all tasks are done.
+macro_rules! join {
+    ($($task:expr,)*) => {join!($($task),*)};
+    ($($task:expr),*) => {{
+        #![allow(clippy::redundant_closure_call)]
+        ::rayon::scope(|scope| {
+            $(scope.spawn(|_| ($task)());)*
+        })
+    }}
+}
+
 fn main() {
     if cfg!(target_os = "windows") {
         // TODO(#2591): Codegen is temporarily disabled on Windows due to hashing issues.
@@ -77,40 +90,35 @@ fn main() {
     let (objects, arrow_registry) =
         re_types_builder::generate_lang_agnostic(DEFINITIONS_DIR_PATH, ENTRYPOINT_PATH);
 
-    join3(
-        || {
-            re_types_builder::generate_cpp_code(
-                &reporter,
-                CPP_OUTPUT_DIR_PATH,
-                &objects,
-                &arrow_registry,
-            );
-        },
-        || {
-            re_types_builder::generate_rust_code(
-                &reporter,
-                RUST_OUTPUT_DIR_PATH,
-                &objects,
-                &arrow_registry,
-            );
-        },
-        || {
-            re_types_builder::generate_python_code(
-                &reporter,
-                PYTHON_OUTPUT_DIR_PATH,
-                PYTHON_TESTING_OUTPUT_DIR_PATH,
-                &objects,
-                &arrow_registry,
-            );
-        },
+    join!(
+        || re_types_builder::generate_cpp_code(
+            &reporter,
+            CPP_OUTPUT_DIR_PATH,
+            &objects,
+            &arrow_registry,
+        ),
+        || re_types_builder::generate_rust_code(
+            &reporter,
+            RUST_OUTPUT_DIR_PATH,
+            &objects,
+            &arrow_registry,
+        ),
+        || re_types_builder::generate_python_code(
+            &reporter,
+            PYTHON_OUTPUT_DIR_PATH,
+            PYTHON_TESTING_OUTPUT_DIR_PATH,
+            &objects,
+            &arrow_registry,
+        ),
+        || re_types_builder::generate_docs(
+            &reporter,
+            DOC_CONTENT_DIR_PATH,
+            &objects,
+            &arrow_registry
+        ),
     );
 
     report.panic_on_errors();
 
     write_versioning_hash(SOURCE_HASH_PATH, new_hash);
 }
-
-// Do 3 things in parallel
-fn join3(a: impl FnOnce() + Send, b: impl FnOnce() + Send, c: impl FnOnce() + Send) {
-    rayon::join(a, || rayon::join(b, c));
-}
diff --git a/crates/re_types/definitions/rerun/archetypes/annotation_context.fbs b/crates/re_types/definitions/rerun/archetypes/annotation_context.fbs
@@ -14,7 +14,9 @@ namespace rerun.archetypes;
 /// path-hierarchy when searching up through the ancestors of a given entity
 /// path.
 ///
-/// \example annotation_context_rects
+/// \example annotation_context_rects title="Rectangles" image="https://static.rerun.io/annotation_context_rects/9b446c36011ed30fce7dc6ed03d5fd9557460f70/1200w.png"
+/// \example annotation_context_segmentation title="Segmentation" image="https://static.rerun.io/annotation_context_segmentation/0e21c0a04e456fec41d16b0deaa12c00cddf2d9b/1200w.png"
+/// \example annotation_context_connections title="Connections" image="https://static.rerun.io/annotation_context_connections/4a8422bc154699c5334f574ff01b55c5cd1748e3/1200w.png"
 table AnnotationContext (
   "attr.rust.derive": "Eq, PartialEq",
   order: 100

diff --git a/crates/re_types/definitions/rerun/archetypes/arrows3d.fbs b/crates/re_types/definitions/rerun/archetypes/arrows3d.fbs
@@ -11,7 +11,7 @@ namespace rerun.archetypes;
 
 /// A batch of 3D arrows with optional colors, radii, labels, etc.
 ///
-/// \example arrow3d_simple
+/// \example arrow3d_simple image="https://static.rerun.io/arrow3d_simple/c8a8b1cbca40acdf02fb5bf264658ad66e07ca40/1200w.png"
 table Arrows3D (
   "attr.rust.derive": "PartialEq",
   "attr.rust.new_pub_crate",

diff --git a/crates/re_types/definitions/rerun/archetypes/asset3d.fbs b/crates/re_types/definitions/rerun/archetypes/asset3d.fbs
@@ -7,7 +7,7 @@ namespace rerun.archetypes;
 
 // ---
 
-/// A prepacked 3D asset (.gltf, .glb, .obj, etc).
+/// A prepacked 3D asset (`.gltf`, `.glb`, `.obj`, etc).
 ///
 /// \example asset3d_simple "Simple 3D asset"
 /// \example asset3d_out_of_tree "3D asset with out-of-tree transform"

diff --git a/crates/re_types/definitions/rerun/archetypes/bar_chart.fbs b/crates/re_types/definitions/rerun/archetypes/bar_chart.fbs
@@ -6,7 +6,7 @@ include "rerun/components.fbs";
 namespace rerun.archetypes;
 
 
-/// A Barchart.
+/// A bar chart.
 ///
 /// The x values will be the indices of the array, and the bar heights will be the provided values.
 ///

diff --git a/crates/re_types/definitions/rerun/archetypes/boxes3d.fbs b/crates/re_types/definitions/rerun/archetypes/boxes3d.fbs
@@ -11,8 +11,8 @@ namespace rerun.archetypes;
 
 /// A batch of 3d boxes with half-extents and optional center, rotations, rotations, colors etc.
 ///
-/// \example box3d_simple "Simple 3D boxes"
-/// \example box3d_batch "Batch of 3D boxes"
+/// \example box3d_simple title="Simple 3D boxes" image="https://static.rerun.io/box3d_simple/d6a3f38d2e3360fbacac52bb43e44762635be9c8/1200w.png"
+/// \example box3d_batch title="Batch of 3D boxes" image="https://static.rerun.io/box3d_batch/28368d2872b2c98186a49fbd063b433e324a88ba/1200w.png"
 table Boxes3D (
   "attr.rust.derive": "PartialEq",
   "attr.rust.new_pub_crate",

diff --git a/crates/re_types/definitions/rerun/archetypes/depth_image.fbs b/crates/re_types/definitions/rerun/archetypes/depth_image.fbs
@@ -11,7 +11,8 @@ namespace rerun.archetypes;
 /// The shape of the `TensorData` must be mappable to an `HxW` tensor.
 /// Each pixel corresponds to a depth value in units specified by `meter`.
 ///
-/// \example depth_image_simple
+/// \example depth_image_simple title="Simple example" image="https://static.rerun.io/depth_image_simple/9598554977873ace2577bddd79184ac120ceb0b0/1200w.png"
+/// \example depth_image_3d title="Depth to 3D example" image="https://static.rerun.io/depth_image_3d/f78674bdae0eb25786c6173307693c5338f38b87/1200w.png"
 table DepthImage (
   "attr.rust.derive": "PartialEq",
   order: 100

diff --git a/crates/re_types/definitions/rerun/archetypes/image.fbs b/crates/re_types/definitions/rerun/archetypes/image.fbs
@@ -16,7 +16,7 @@ namespace rerun.archetypes;
 /// Leading and trailing unit-dimensions are ignored, so that
 /// `1x640x480x3x1` is treated as a `640x480x3` RGB image.
 ///
-/// \example image_simple
+/// \example image_simple image="https://static.rerun.io/image_simple/06ba7f8582acc1ffb42a7fd0006fad7816f3e4e4/1200w.png"
 table Image (
   "attr.rust.derive": "PartialEq",
   order: 100

diff --git a/crates/re_types/definitions/rerun/archetypes/line_strips2d.fbs b/crates/re_types/definitions/rerun/archetypes/line_strips2d.fbs
@@ -9,8 +9,9 @@ namespace rerun.archetypes;
 
 /// A batch of line strips with positions and optional colors, radii, labels, etc.
 ///
-/// \example line_strip2d_batch "Many strips"
-/// \example line_segments2d_simple "Many individual segments"
+/// \example line_strip2d_simple image="https://static.rerun.io/line_strip2d_simple/c4e6ce937544e66b497450fd64ac3ac2f244f0e1/1200w.png"
+/// \example line_segments2d_simple image="https://static.rerun.io/line_segment2d_simple/53df596662dd9ffaaea5d09d091ef95220346c83/1200w.png"
+/// \example line_strip2d_batch image="https://static.rerun.io/line_strip2d_batch/d8aae7ca3d6c3b0e3b636de60b8067fa2f0b6db9/1200w.png"
 table LineStrips2D (
   "attr.rust.derive": "PartialEq",
   order: 100

diff --git a/crates/re_types/definitions/rerun/archetypes/line_strips3d.fbs b/crates/re_types/definitions/rerun/archetypes/line_strips3d.fbs
@@ -9,8 +9,9 @@ namespace rerun.archetypes;
 
 /// A batch of line strips with positions and optional colors, radii, labels, etc.
 ///
-/// \example line_strip3d_batch "Many strips"
-/// \example line_segments3d_simple "Many individual segments"
+/// \example line_strip3d_simple title="Simple example" image="https://static.rerun.io/line_strip3d_simple/13036c0e71f78d3cec37d5724f97b47c4cf3c429/1200w.png"
+/// \example line_segments3d_simple title="Many individual segments" image="https://static.rerun.io/line_segment3d_simple/aa800b2a6e6a7b8e32e762b42861bae36f5014bb/1200w.png"
+/// \example line_strip3d_batch title="Many strips" image="https://static.rerun.io/line_strip3d_batch/102e5ec5271475657fbc76b469267e4ec8e84337/1200w.png"
 table LineStrips3D (
   "attr.rust.derive": "PartialEq",
   order: 100

diff --git a/crates/re_types/definitions/rerun/archetypes/pinhole.fbs b/crates/re_types/definitions/rerun/archetypes/pinhole.fbs
@@ -8,7 +8,7 @@ namespace rerun.archetypes;
 
 /// Camera perspective projection (a.k.a. intrinsics).
 ///
-/// \example pinhole_simple
+/// \example pinhole_simple image="https://static.rerun.io/pinhole_simple/9af9441a94bcd9fd54e1fea44fb0c59ff381a7f2/1200w.png"
 table Pinhole (
   "attr.rust.derive": "PartialEq",
   order: 100

diff --git a/crates/re_types/definitions/rerun/archetypes/points2d.fbs b/crates/re_types/definitions/rerun/archetypes/points2d.fbs
@@ -12,7 +12,8 @@ namespace rerun.archetypes;
 
 /// A 2D point cloud with positions and optional colors, radii, labels, etc.
 ///
-/// \example point2d_simple
+/// \example point2d_simple image="https://static.rerun.io/point2d_simple/a8e801958bce5aa4e080659c033630f86ce95f71/1200w.png"
+/// \example point2d_random image="https://static.rerun.io/point2d_random/8e8ac75373677bd72bd3f56a15e44fcab309a168/1200w.png"
 table Points2D (
   "attr.rust.derive": "PartialEq",
   order: 100

diff --git a/crates/re_types/definitions/rerun/archetypes/points3d.fbs b/crates/re_types/definitions/rerun/archetypes/points3d.fbs
@@ -9,7 +9,8 @@ namespace rerun.archetypes;
 
 /// A 3D point cloud with positions and optional colors, radii, labels, etc.
 ///
-/// \example point3d_simple
+/// \example point3d_simple image="https://static.rerun.io/point3d_simple/32fb3e9b65bea8bd7ffff95ad839f2f8a157a933/1200w.png"
+/// \example point3d_random image="https://static.rerun.io/point3d_random/7e94e1806d2c381943748abbb3bedb68d564de24/1200w.png"
 table Points3D (
   "attr.rust.derive": "PartialEq",
   order: 100

diff --git a/crates/re_types/definitions/rerun/archetypes/segmentation_image.fbs b/crates/re_types/definitions/rerun/archetypes/segmentation_image.fbs
@@ -14,7 +14,7 @@ namespace rerun.archetypes;
 /// Leading and trailing unit-dimensions are ignored, so that
 /// `1x640x480x1` is treated as a `640x480` image.
 ///
-/// \example segmentation_image_simple
+/// \example segmentation_image_simple image="https://static.rerun.io/segmentation_image_simple/eb49e0b8cb870c75a69e2a47a2d202e5353115f6/1200w.png"
 table SegmentationImage (
   "attr.rust.derive": "PartialEq",
   order: 100

diff --git a/crates/re_types/definitions/rerun/archetypes/tensor.fbs b/crates/re_types/definitions/rerun/archetypes/tensor.fbs
@@ -8,7 +8,8 @@ namespace rerun.archetypes;
 
 /// A generic n-dimensional Tensor.
 ///
-/// \example tensor_simple
+/// \example tensor_simple image="https://static.rerun.io/tensor_simple/1aead2554496737e9267a5ab5220dbc89da851ee/1200w.png"
+/// \example tensor_one_dim image="https://static.rerun.io/tensor_one_dim/cbf24b466fe9d9639777aefb34f1a00c3f30d7ab/1200w.png"
 table Tensor (
   "attr.rust.derive": "PartialEq",
   order: 100

diff --git a/crates/re_types/definitions/rerun/archetypes/time_series_scalar.fbs b/crates/re_types/definitions/rerun/archetypes/time_series_scalar.fbs
@@ -7,7 +7,7 @@ namespace rerun.archetypes;
 
 // ---
 
-/// Log a double-precision scalar that will be visualized as a timeseries plot.
+/// Log a double-precision scalar that will be visualized as a time-series plot.
 ///
 /// The current simulation time will be used for the time/X-axis, hence scalars
 /// cannot be timeless!

diff --git a/crates/re_types/definitions/rerun/archetypes/transform3d.fbs b/crates/re_types/definitions/rerun/archetypes/transform3d.fbs
@@ -8,7 +8,7 @@ namespace rerun.archetypes;
 
 /// A 3D transform.
 ///
-/// \example transform3d_simple
+/// \example transform3d_simple image="https://static.rerun.io/transform3d_simple/141368b07360ce3fcb1553079258ae3f42bdb9ac/1200w.png"
 table Transform3D (
   "attr.rust.derive": "PartialEq",
   order: 100

diff --git a/crates/re_types/src/archetypes/annotation_context.rs b/crates/re_types/src/archetypes/annotation_context.rs
diff --git a/crates/re_types/src/archetypes/arrows3d.rs b/crates/re_types/src/archetypes/arrows3d.rs