Various C++ docs improvements (#4329)

### What

Lots of small stuff. Biggest thing is probably the move of two pages out
of our general docs into cpp api docs.
Commit by commit!

### 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/4329) (if
applicable)
* [x] The PR title and labels are set such as to maximize their
usefulness for the next release's CHANGELOG

- [PR Build Summary](https://build.rerun.io/pr/4329)
- [Docs
preview](https://rerun.io/preview/b8c696788c92cb6a55796cf03391d4d8fe84d97e/docs)
<!--DOCS-PREVIEW-->
- [Examples
preview](https://rerun.io/preview/b8c696788c92cb6a55796cf03391d4d8fe84d97e/examples)
<!--EXAMPLES-PREVIEW-->
- [Recent benchmark results](https://build.rerun.io/graphs/crates.html)
- [Wasm size tracking](https://build.rerun.io/graphs/sizes.html)

crates/re_renderer/src/wgpu_resources/bind_group_pool.rs

@@ -80,7 +80,7 @@ impl DynamicResourcesDesc for BindGroupDesc {
 /// * owned [`wgpu::BindGroup`] should keep buffer/texture alive
 ///   (user should not need to hold buffer/texture manually)
 /// * [`GpuBindGroupPool`] should *try* to re-use previously created bind groups if they happen to match
-/// * musn't prevent buffer/texture re-use on next frame
+/// * mustn't prevent buffer/texture re-use on next frame
 ///   i.e. a internally cached [`GpuBindGroupPool`]s without owner shouldn't keep textures/buffers alive
 ///
 /// We satisfy these by retrieving the "weak" buffer/texture handles and make them part of the [`GpuBindGroup`].

crates/re_space_view/src/space_view_contents.rs

@@ -27,7 +27,7 @@ pub struct DataBlueprintGroup {
 
     /// Direct child entities of this blueprint group.
     ///
-    /// Musn't be a `HashSet` because we want to preserve order of entity paths.
+    /// Mustn't be a `HashSet` because we want to preserve order of entity paths.
     pub entities: BTreeSet<EntityPath>,
 }
 

crates/re_viewer/data/quick_start_guides/cpp_connect.md

@@ -22,7 +22,7 @@ FetchContent_MakeAvailable(rerun_sdk)
 This will download a bundle with pre-built Rerun C static libraries for most desktop platforms,
 all Rerun C++ sources and headers, as well as CMake build instructions for them.
 By default this will in turn download & build [Apache Arrow](https://arrow.apache.org/)'s C++ library which is required to build the Rerun C++.
-See [Install arrow-cpp](https://www.rerun.io/docs/howto/arrow-cpp-install) to learn more about this step and how to use an existing install.
+See [Install arrow-cpp](https://ref.rerun.io/docs/cpp/latest/md__arrow__cpp__install.html?speculative-link) to learn more about this step and how to use an existing install.
 
 Make sure you link with `rerun_sdk`:
 ```cmake

crates/re_viewer_context/src/space_view/view_part_system.rs

@@ -83,7 +83,7 @@ pub trait ViewPartSystem {
 
     /// Queries the data store and performs data conversions to make it ready for display.
     ///
-    /// Musn't query any data outside of the archetype.
+    /// Mustn't query any data outside of the archetype.
     ///
     /// TODO(andreas): don't pass in `ViewerContext` if we want to restrict the queries here.
     /// If we want to make this restriction, then the trait-contract should be that something external

docs/code-examples/asset3d_out_of_tree.cpp

@@ -22,11 +22,7 @@ int main(int argc, char** argv) {
     // Those points will not be affected by their parent's out-of-tree transform!
     rec.log(
         "world/asset/points",
-        rerun::Points3D(rerun::demo::grid<rerun::Position3D, float>(
-            {-10.0f, -10.0f, -10.0f},
-            {10.0f, 10.0f, 10.0f},
-            10
-        ))
+        rerun::Points3D(rerun::demo::grid3d<rerun::Position3D, float>(-10.0f, 10.0f, 10))
     );
 
     for (int64_t i = 1; i < 20; ++i) {

docs/code-examples/custom_data.cpp

@@ -3,14 +3,12 @@
 #include <rerun.hpp>
 #include <rerun/demo_utils.hpp>
 
-/// A custom component that is backed by a builtin `rerun::Float32` scalar `rerun::Datatype`.
-/// Using a rerun type allows us to re-use the existing arrow serialization code.
+/// A custom component type.
 struct Confidence {
-    rerun::Float32 value;
+    float value;
 };
 
-/// A custom component bundle that extends Rerun's builtin `rerun::Points3D` archetype with extra
-/// `rerun::Component`s.
+/// A custom archetype that extends Rerun's builtin `rerun::Points3D` archetype with a custom component.
 struct CustomPoints3D {
     static constexpr const char IndicatorName[] = "user.CustomPoints3DIndicator";
     using IndicatorComponent = rerun::components::IndicatorComponent<IndicatorName>;
@@ -66,8 +64,7 @@ int main() {
     const auto rec = rerun::RecordingStream("rerun_example_custom_data");
     rec.spawn().exit_on_failure();
 
-    auto grid =
-        rerun::demo::grid<rerun::Position3D, float>({-5.0f, -5.0f, -5.0f}, {5.0f, 5.0f, 5.0f}, 3);
+    auto grid = rerun::demo::grid3d<rerun::Position3D, float>(-5.0f, 5.0f, 3);
 
     rec.log(
         "left/my_confident_point_cloud",

docs/code-examples/custom_data.py

@@ -27,6 +27,8 @@ def as_arrow_array(self) -> pa.Array:
 
 
 class CustomPoints3D(rr.AsComponents):
+    """A custom archetype that extends Rerun's builtin `Points3D` archetype with a custom component."""
+
     def __init__(self: Any, points3d: npt.ArrayLike, confidences: npt.ArrayLike) -> None:
         self.points3d = points3d
         self.confidences = confidences

docs/code-examples/quick_start_connect.cpp

@@ -9,8 +9,8 @@ int main() {
     rec.spawn().exit_on_failure();
 
     // Create some data using the `grid` utility function.
-    auto points = grid<rerun::Position3D, float>({-10.f, -10.f, -10.f}, {10.f, 10.f, 10.f}, 10);
-    auto colors = grid<rerun::Color, uint8_t>({0, 0, 0}, {255, 255, 255}, 10);
+    std::vector<rerun::Position3D> points = grid3d<rerun::Position3D, float>(-10.f, 10.f, 10);
+    std::vector<rerun::Color> colors = grid3d<rerun::Color, uint8_t>(0, 255, 10);
 
     // Log the "my_points" entity with our data, using the `Points3D` archetype.
     rec.log("my_points", rerun::Points3D(points).with_colors(colors).with_radii({0.5f}));

docs/content/getting-started/cpp.md

@@ -31,7 +31,7 @@ FetchContent_MakeAvailable(rerun_sdk)
 This will download a bundle with pre-built Rerun C static libraries for most desktop platforms,
 all Rerun C++ sources and headers, as well as CMake build instructions for them.
 By default this will in turn download & build [Apache Arrow](https://arrow.apache.org/)'s C++ library which is required to build the Rerun C++.
-See [Install arrow-cpp](../howto/arrow-cpp-install.md) to learn more about this step and how to use an existing install.
+See [Install arrow-cpp](https://ref.rerun.io/docs/cpp/latest/md__arrow__cpp__install.html?speculative-link) to learn more about this step and how to use an existing install.
 
 Currently, Rerun SDK works with C++17 or newer, so you need to add this property to your target:
 
@@ -83,8 +83,8 @@ int main() {
     rec.spawn().exit_on_failure();
 
     // Create some data using the `grid` utility function.
-    auto points = grid<rerun::Position3D, float>({-10.f, -10.f, -10.f}, {10.f, 10.f, 10.f}, 10);
-    auto colors = grid<rerun::Color, uint8_t>({0, 0, 0}, {255, 255, 255}, 10);
+    std::vector<rerun::Position3D> points = grid3d<rerun::Position3D, float>(-10.f, 10.f, 10);
+    std::vector<rerun::Color> colors = grid3d<rerun::Color, uint8_t>(0, 255, 10);
 
     // Log the "my_points" entity with our data, using the `Points3D` archetype.
     rec.log("my_points", rerun::Points3D(points).with_colors(colors).with_radii({0.5f}));
@@ -131,4 +131,4 @@ There's also a stand-alone example that shows [interop with Eigen and OpenCV](ht
 
 TODO(#3977): Note that this is still an area of active development and there's going to be major improvements for library interop in upcoming versions.
 
-To learn more about how to configure the C++ SDK's CMake file, check [C++ SDK CMake](../reference/cpp-sdk-cmake.md).
+To learn more about how to configure the C++ SDK's CMake file, check [CMake Setup in Detail](https://ref.rerun.io/docs/cpp/latest/md__cmake__setup__in__detail.html?speculative-link) .

docs/content/getting-started/logging-cpp.md

@@ -38,7 +38,7 @@ You should have already [installed the viewer](installing-viewer.md).
 
 We assume you have a working C++ toolchain and are using `CMake` to build your project. For this example
 we will let Rerun download build [Apache Arrow](https://arrow.apache.org/)'s C++ library itself.
-See [Install arrow-cpp](../howto/arrow-cpp-install.md) to learn more about this step and how to use an existing install.
+See [Install arrow-cpp](https://ref.rerun.io/docs/cpp/latest/md__arrow__cpp__install.html?speculative-link) to learn more about this step and how to use an existing install.
 
 ## Setting up your CMakeLists.txt
 

docs/cspell.json

@@ -174,6 +174,7 @@
     "llvmpipe",
     "loggable",
     "logtype",
+    "mainpage",
     "Malik",
     "Mathieu",
     "maturin",
@@ -309,6 +310,7 @@
     "structs",
     "subdir",
     "superquadrics",
+    "tableofcontents",
     "taplo",
     "Tete",
     "Tewari",

examples/cpp/CMakeLists.txt

@@ -2,11 +2,11 @@ add_subdirectory(clock)
 add_subdirectory(dna)
 add_subdirectory(minimal)
 add_subdirectory(spawn_viewer)
-add_subdirectory(custom_component_adapter)
+add_subdirectory(custom_collection_adapter)
 
 add_custom_target(examples)
 add_dependencies(examples example_clock)
 add_dependencies(examples example_dna)
 add_dependencies(examples example_minimal)
 add_dependencies(examples example_spawn_viewer)
-add_dependencies(examples example_custom_component_adapter)
+add_dependencies(examples example_custom_collection_adapter)

examples/cpp/custom_component_adapter/CMakeLists.txt → examples/cpp/custom_collection_adapter/CMakeLists.txt

@@ -4,12 +4,12 @@ cmake_minimum_required(VERSION 3.16...3.27)
 # where the rerun_c build is to be found by setting the `RERUN_CPP_URL` variable.
 # This can be done by passing `-DRERUN_CPP_URL=<path to rerun_sdk_cpp zip>` to cmake.
 if(DEFINED RERUN_REPOSITORY)
-    add_executable(example_custom_component_adapter main.cpp)
-    rerun_strict_warning_settings(example_custom_component_adapter)
+    add_executable(example_custom_collection_adapter main.cpp)
+    rerun_strict_warning_settings(example_custom_collection_adapter)
 else()
-    project(example_custom_component_adapter LANGUAGES CXX)
+    project(example_custom_collection_adapter LANGUAGES CXX)
 
-    add_executable(example_custom_component_adapter main.cpp)
+    add_executable(example_custom_collection_adapter main.cpp)
 
     # Set the path to the rerun_c build.
     set(RERUN_CPP_URL "https://github.com/rerun-io/rerun/releases/latest/download/rerun_cpp_sdk.zip" CACHE STRING "URL to the rerun_cpp zip.")
@@ -20,8 +20,8 @@ else()
     FetchContent_MakeAvailable(rerun_sdk)
 
     # Rerun requires at least C++17, but it should be compatible with newer versions.
-    set_property(TARGET example_custom_component_adapter PROPERTY CXX_STANDARD 17)
+    set_property(TARGET example_custom_collection_adapter PROPERTY CXX_STANDARD 17)
 endif()
 
 # Link against rerun_sdk.
-target_link_libraries(example_custom_component_adapter PRIVATE rerun_sdk)
+target_link_libraries(example_custom_collection_adapter PRIVATE rerun_sdk)

examples/cpp/custom_collection_adapter/README.md

@@ -0,0 +1,30 @@
+# Custom Collection Adapter
+
+Especially when dealing with large amounts of data, it can be both slow and inconvenient to convert
+your data into the components & datatypes provided by the Rerun SDK in order to log it.
+
+This example demonstrates how to solve this using [`rerun::ComponentAdapter`](https://ref.rerun.io/docs/cpp/latest/structrerun_1_1CollectionAdapter.html?speculative-link) for your own types:
+Whenever you have data that is continuous in memory and binary compatible with an existing Rerun component,
+you can adapt it to map to the respective Rerun component.
+<!-- direct link to log method? speculative-link doesn't seem to work with that https://ref.rerun.io/docs/cpp/latest/classrerun_1_1RecordingStream.html#af7a14a7e2c3029ef1679ff9fd680129d -->
+For non-temporary objects that live until [`rerun::RecordingStream::log`](https://ref.rerun.io/docs/cpp/latest/classrerun_1_1RecordingStream.html?speculative-link) returns,
+it is typically safe to do so with a zero-copy "borrow".
+This means that in those cases [`rerun::Collection`](https://ref.rerun.io/docs/cpp/latest/classrerun_1_1Collection.html?speculative-link) will merely store a pointer and a length to your data.
+
+While collection adapters are primarily used with components, they are also useful for all other usages of
+rerun's collection type. E.g. the backing buffer of [`rerun::TensorData`](https://ref.rerun.io/docs/cpp/latest/structrerun_1_1datatypes_1_1TensorBuffer.html?speculative-link)
+is also a [`rerun::Collection`](https://ref.rerun.io/docs/cpp/latest/classrerun_1_1Collection.html?speculative-link)
+allowing you to ingest large amounts of data without a copy and the convenience custom adapters can provide.
+
+
+To build it from a checkout of the repository (requires a Rust toolchain):
+```bash
+cmake .
+cmake --build . --target example_custom_collection_adapter
+./examples/cpp/minimal/example_custom_collection_adapter
+```
+
+---
+
+* 🚧 TODO(#4257): In the future, adapters will be able to provide simple data transformations like strides to be done as a borrow.
+* 🚧 TODO(#3977): We plan to provide adapters for common types from Eigen and OpenCV.

examples/cpp/minimal/main.cpp

@@ -1,7 +1,7 @@
 #include <rerun.hpp>
 #include <rerun/demo_utils.hpp>
 
-using rerun::demo::grid;
+using rerun::demo::grid3d;
 
 int main() {
     // Create a new `RecordingStream` which sends data over TCP to the viewer process.
@@ -10,8 +10,8 @@ int main() {
     rec.spawn().exit_on_failure();
 
     // Create some data using the `grid` utility function.
-    auto points = grid<rerun::Position3D, float>({-10.f, -10.f, -10.f}, {10.f, 10.f, 10.f}, 10);
-    auto colors = grid<rerun::Color, uint8_t>({0, 0, 0}, {255, 255, 255}, 10);
+    std::vector<rerun::Position3D> points = grid3d<rerun::Position3D, float>(-10.f, 10.f, 10);
+    std::vector<rerun::Color> colors = grid3d<rerun::Color, uint8_t>(0, 255, 10);
 
     // Log the "my_points" entity with our data, using the `Points3D` archetype.
     rec.log("my_points", rerun::Points3D(points).with_colors(colors).with_radii({0.5f}));

pixi.toml

@@ -76,7 +76,7 @@ cpp-log-benchmark = { cmd = "export RERUN_STRICT=1 && ./build/release/tests/cpp/
   "cpp-build-log-benchmark",
 ] }
 cpp-build-and-test-all = { depends_on = ["cpp-build-all", "cpp-test"] }
-cpp-docs = { cmd = "doxygen rerun_cpp/docs/Doxyfile && echo '***************\nSuccess!\nOpen ./rerun_cpp/docs/html/index.html in your browser.'" }
+cpp-docs = { cmd = "doxygen docs/Doxyfile && echo '***************\nSuccess!\nOpen ./rerun_cpp/docs/html/index.html in your browser.'", cwd = "rerun_cpp" }
 
 [target.win-64.tasks]
 cpp-prepare-msvc = "cmake -G 'Visual Studio 17 2022' -B build-msvc -S ."

rerun_cpp/CMakeLists.txt

@@ -178,7 +178,7 @@ install(FILES
 
 # -----------------------------------------------------------------------------
 # Add tests if they exist (they are not part of the distribution zip).
-# Has direct dpeendency to arrow, so needs to happen last.
+# Has direct dependency to arrow, so needs to happen last.
 if(EXISTS tests)
     add_subdirectory(tests)
 endif()

rerun_cpp/README.md

@@ -1,3 +1,6 @@
+\mainpage
+\tableofcontents
+
 # Rerun C++ SDK
 
 The Rerun C++ SDK allows logging data to Rerun directly from C++.
@@ -51,7 +54,7 @@ The built-in types are distributed to the respective namespaces:
 * `rerun::components`
 * `rerun::datatypes`
 
-If you include `rerun.hpp`, all archetypes and selected components become part of the `rerun` namespace.
+If you include `rerun.hpp`, all archetypes and most component types become part of the `rerun` namespace.
 
 Check the [general doc page on types](https://www.rerun.io/docs/reference/types) to learn more.
 
@@ -65,30 +68,30 @@ the C++ SDK is expected to be built from source.
 From a build system perspective, the SDK consists of three dependencies:
 
 * [SDK source](https://github.com/rerun-io/rerun/tree/latest/rerun_cpp/src/)
-  * this includes **both** source and header files!
+  * This includes **both** source and header files!
 * [rerun_c](https://github.com/rerun-io/rerun/tree/latest/crates/rerun_c/) static libraries
   * Rerun C is a minimal C SDK and forms the bridge to the shared Rust codebase
-  * due to the rigidity of the C ABI and lack of complex standard library types in the interface,
+  * Due to the rigidity of the C ABI and lack of complex standard library types in the interface,
     compatibility issues between compilers are less of a concern
-    which is why offer pre-built libraries with every release for all major platforms
+    which is why we offer pre-built libraries with every release for all major platforms
 * [Apache Arrow C++ library](https://arrow.apache.org/docs/cpp/index.html)
   * The SDK uses this library to perform all serialization before handing data over to rerun_c
-  * See [Install arrow-cpp](https://www.rerun.io/docs/howto/arrow-cpp-install) for how to install this library
+  * See [Install arrow-cpp](arrow_cpp_install.md) for how to install this library
 
 
 ### SDK bundle (rerun_cpp_sdk.zip)
 
 For convenience, Rerun provides a C++ SDK bundle with every release.
 (this includes our regular [Development Builds](https://github.com/rerun-io/rerun/releases/tag/prerelease)!)
 
-This is a simple zip archive containing the SDK the [repository](https://github.com/rerun-io/rerun/tree/latest/rerun_cpp)
-(excluding the tests folder) and a `lib` folder with prebuilt rerun_c libraries for all major desktop platforms.
+This is a simple zip archive containing the SDK from the [repository](https://github.com/rerun-io/rerun/tree/latest/rerun_cpp)
+(excluding the `tests` folder) and a `lib` folder with prebuilt rerun_c libraries for all major desktop platforms.
 The rerun_c libraries follow a simple name schema that the CMake script can pick up.
 
 
 ### Building with CMake
 
-See [C++ SDK CMake](https://www.rerun.io/docs/reference/cpp-sdk-cmake) for deeper dive on
+See [CMake Setup in Detail](cmake_setup_in_detail.md) for deeper dive on
 how to use the SDK's `CMakeLists.txt` and an overview over all CMake configuration options.
 
 ### Without CMake
@@ -99,7 +102,7 @@ but it should be possible to setup Rerun C++ without CMake fairly easily:
 You have to add all files from the [src/](https://github.com/rerun-io/rerun/tree/latest/rerun_cpp/src/) folder
 either directly to your project or a library.
 In addition, you need to link the `rerun_c` libraries and the [Arrow C++ library](https://arrow.apache.org/docs/cpp/index.html).
-For more information on how to install Arrow, see [Install arrow-cpp](https://www.rerun.io/docs/howto/arrow-cpp-install).
+For more information on how to install Arrow, see [Install arrow-cpp](arrow_cpp_install.md).
 
 Make sure to compile with C++17 or newer.
 
@@ -116,3 +119,12 @@ Keep in mind that all archetypes/components/datatypes are mostly generated by th
 Use `just codegen` to run code generation. Generally, all generated code files are part of the repository,
 so you only have to do that if you change the data definition or make changes to `_ext.cpp` files which
 extend generated types.
+
+## Tested compilers
+
+The Rerun C++ SDK requires a C++17 compliant compiler.
+
+As of writing we tested the SDK against:
+* Apple Clang 14, 15
+* GCC 9, 10, 12
+* Visual Studio 2022

docs/content/howto/arrow-cpp-install.md → rerun_cpp/arrow_cpp_install.md

@@ -1,7 +1,6 @@
----
-title: Install arrow-cpp
-order: 6
----
+# Installing ArrowCpp separately
+
+\tableofcontents
 
 ## Automatically download & build arrow from source (default)
 
@@ -13,7 +12,7 @@ To instead use an existing install of Arrow, disable the CMake build option `RER
 (by passing `-DRERUN_DOWNLOAD_AND_BUILD_ARROW=OFF` to your CMake configure step).
 This will cause Rerun to instead use CMake's `find_package` to look for a ready-to-use install of the Arrow C++ library.
 
-For more information about CMake config options see [C++ SDK CMake](../reference/cpp-sdk-cmake.md).
+For more information about CMake config options see [C++ SDK CMake](cmake_setup_in_detail.md).
 
 ## Install arrow-cpp with Pixi