Generate doc pages for blueprint views (#6121)

### What
- Builds on top of: #6120
  - Rebase after merging and then remove `do-no-merge` label.

Add blueprint views to the python docs index.

Create a reference page for each view with documentation of its view
properties and an example when provided.

Generating pages for all the blueprint archetypes and cross-linking
still felt a bit overwhelming. Since these properties are almost always
only used in the context of the view, I decided to inline instead.

### 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 the web demo (if applicable):
* Using examples from latest `main` build:
[rerun.io/viewer](https://rerun.io/viewer/pr/6121?manifest_url=https://app.rerun.io/version/main/examples_manifest.json)
* Using full set of examples from `nightly` build:
[rerun.io/viewer](https://rerun.io/viewer/pr/6121?manifest_url=https://app.rerun.io/version/nightly/examples_manifest.json)
* [x] The PR title and labels are set such as to maximize their
usefulness for the next release's CHANGELOG
* [x] If applicable, add a new check to the [release
checklist](https://github.com/rerun-io/rerun/blob/main/tests/python/release_checklist)!

- [PR Build Summary](https://build.rerun.io/pr/6121)
- [Recent benchmark results](https://build.rerun.io/graphs/crates.html)
- [Wasm size tracking](https://build.rerun.io/graphs/sizes.html)

To run all checks from `main`, comment on the PR with `@rerun-bot
full-check`.

crates/re_types/definitions/rerun/blueprint/views/spatial3d.fbs

@@ -3,6 +3,8 @@ include "rerun/attributes.fbs";
 namespace rerun.blueprint.views;
 
 /// A Spatial 3D view.
+///
+/// \example spatial3dview title="Use a blueprint to customize a Spatial3DView"
 table Spatial3DView (
     "attr.rerun.view_identifier": "3D"
 ) {

crates/re_types_builder/src/codegen/docs/mod.rs

@@ -39,7 +39,8 @@ impl CodeGenerator for DocsCodeGenerator {
 
         let mut files_to_write = GeneratedFiles::default();
 
-        let (mut archetypes, mut components, mut datatypes) = (Vec::new(), Vec::new(), Vec::new());
+        let (mut archetypes, mut components, mut datatypes, mut views) =
+            (Vec::new(), Vec::new(), Vec::new(), Vec::new());
         let object_map = &objects.objects;
         for object in object_map.values() {
             // skip test-only archetypes
@@ -48,18 +49,15 @@ impl CodeGenerator for DocsCodeGenerator {
             }
 
             // Skip blueprint stuff, too early
-            if object.scope() == Some("blueprint".to_owned()) {
+            if object.scope() == Some("blueprint".to_owned()) && object.kind != ObjectKind::View {
                 continue;
             }
 
             match object.kind {
                 ObjectKind::Datatype => datatypes.push(object),
                 ObjectKind::Component => components.push(object),
                 ObjectKind::Archetype => archetypes.push(object),
-                ObjectKind::View => {
-                    // TODO(#6082): Implement view docs generation.
-                    continue;
-                }
+                ObjectKind::View => views.push(object),
             }
 
             let page = object_page(reporter, object, object_map);
@@ -96,6 +94,12 @@ on [Entities and Components](../../concepts/entity-component.md).",
                 r"Data types are the lowest layer of the data model hierarchy. They are re-usable types used by the components.",
                 &datatypes,
             ),
+            (
+                ObjectKind::View,
+                4,
+                r"Views are the panels shown in the viewer's viewport and the primary means of inspecting & visualizing previously logged data. This page lists all built-in views.",
+                &views,
+            ),
         ] {
             let page = index_page(kind, order, prelude, objects);
             let path = self
@@ -216,7 +220,8 @@ fn object_page(reporter: &Reporter, object: &Object, object_map: &ObjectMap) ->
         }
         ObjectKind::Archetype => write_archetype_fields(&mut page, object, object_map),
         ObjectKind::View => {
-            // TODO(#6082): Implement view docs generation.
+            // TODO(#6082): Views should include the archetypes they know how to show
+            write_view_properties(reporter, &mut page, object, object_map);
         }
     }
 
@@ -226,48 +231,65 @@ fn object_page(reporter: &Reporter, object: &Object, object_map: &ObjectMap) ->
         } else {
             ""
         };
+
         putln!(page);
         putln!(page, "## Links");
 
-        let cpp_link = if object.is_enum() {
-            // Can't link to enums directly 🤷
-            format!(
-                "https://ref.rerun.io/docs/cpp/stable/namespacererun_1_1{}.html",
-                object.kind.plural_snake_case()
-            )
+        if object.kind == ObjectKind::View {
+            // More complicated link due to scope
+            putln!(
+                page,
+                " * 🐍 [Python API docs for `{}`](https://ref.rerun.io/docs/python/stable/common/{}_{}{}#rerun.{}.{}.{})",
+                object.name,
+                object.scope().unwrap_or_default(),
+                object.kind.plural_snake_case(),
+                speculative_marker,
+                object.scope().unwrap_or_default(),
+                object.kind.plural_snake_case(),
+                object.name
+            );
         } else {
-            // `_1` is doxygen's replacement for ':'
-            // https://github.com/doxygen/doxygen/blob/Release_1_9_8/src/util.cpp#L3532
-            format!(
-                "https://ref.rerun.io/docs/cpp/stable/structrerun_1_1{}_1_1{}.html",
+            let cpp_link = if object.is_enum() {
+                // Can't link to enums directly 🤷
+                format!(
+                    "https://ref.rerun.io/docs/cpp/stable/namespacererun_1_1{}.html",
+                    object.kind.plural_snake_case()
+                )
+            } else {
+                // `_1` is doxygen's replacement for ':'
+                // https://github.com/doxygen/doxygen/blob/Release_1_9_8/src/util.cpp#L3532
+                format!(
+                    "https://ref.rerun.io/docs/cpp/stable/structrerun_1_1{}_1_1{}.html",
+                    object.kind.plural_snake_case(),
+                    object.name
+                )
+            };
+
+            // In alphabetical order by language.
+            putln!(
+                page,
+                " * 🌊 [C++ API docs for `{}`]({cpp_link}{speculative_marker})",
+                object.name,
+            );
+            putln!(
+                page,
+                " * 🐍 [Python API docs for `{}`](https://ref.rerun.io/docs/python/stable/common/{}{}#rerun.{}.{})",
+                object.name,
+                object.kind.plural_snake_case(),
+                speculative_marker,
                 object.kind.plural_snake_case(),
                 object.name
-            )
-        };
+            );
 
-        // In alphabetical order by language.
-        putln!(
-            page,
-            " * 🌊 [C++ API docs for `{}`]({cpp_link}{speculative_marker})",
-            object.name,
-        );
-        putln!(
-            page,
-            " * 🐍 [Python API docs for `{}`](https://ref.rerun.io/docs/python/stable/common/{}{}#rerun.{}.{})",
-            object.name,
-            object.kind.plural_snake_case(),
-            speculative_marker,
-            object.kind.plural_snake_case(),
-            object.name
-        );
-        putln!(
-            page,
-            " * 🦀 [Rust API docs for `{}`](https://docs.rs/rerun/latest/rerun/{}/{}.{}.html{speculative_marker})",
-            object.name,
-            object.kind.plural_snake_case(),
-            if object.is_struct() { "struct" } else { "enum" },
-            object.name,
-        );
+            putln!(
+                page,
+                " * 🦀 [Rust API docs for `{}`](https://docs.rs/rerun/latest/rerun/{}/{}.{}.html{speculative_marker})",
+                object.name,
+                object.kind.plural_snake_case(),
+                if object.is_struct() { "struct" } else { "enum" },
+                object.name,
+            );
+        }
     }
 
     putln!(page);
@@ -476,6 +498,74 @@ fn write_archetype_fields(o: &mut String, object: &Object, object_map: &ObjectMa
     }
 }
 
+fn write_view_properties(
+    reporter: &Reporter,
+    o: &mut String,
+    object: &Object,
+    object_map: &ObjectMap,
+) {
+    if object.fields.is_empty() {
+        return;
+    }
+
+    putln!(o, "## Properties");
+    putln!(o);
+
+    // Each field in a view should be a property
+    for field in &object.fields {
+        let Some(fqname) = field.typ.fqname() else {
+            continue;
+        };
+        let Some(ty) = object_map.get(fqname) else {
+            continue;
+        };
+        write_view_property(reporter, o, ty, object_map);
+    }
+}
+
+fn write_view_property(
+    reporter: &Reporter,
+    o: &mut String,
+    object: &Object,
+    _object_map: &ObjectMap,
+) {
+    putln!(o, "### `{}`", object.name);
+
+    let top_level_docs = object.docs.untagged();
+
+    if top_level_docs.is_empty() {
+        reporter.error(
+            &object.virtpath,
+            &object.fqname,
+            "Undocumented view property",
+        );
+    }
+
+    for line in top_level_docs {
+        putln!(o, "{line}");
+    }
+
+    if object.fields.is_empty() {
+        return;
+    }
+
+    let mut fields = Vec::new();
+    for field in &object.fields {
+        fields.push(format!(
+            "* {}: {}",
+            field.name,
+            field.docs.first_line().unwrap_or_default()
+        ));
+    }
+
+    if !fields.is_empty() {
+        putln!(o);
+        for field in fields {
+            putln!(o, "{field}");
+        }
+    }
+}
+
 fn write_example_list(o: &mut String, examples: &[ExampleInfo<'_>]) {
     if examples.is_empty() {
         return;

rerun_py/docs/gen_common_index.py

@@ -280,6 +280,12 @@ class Section:
         mod_path="rerun.blueprint.components",
         show_tables=False,
     ),
+    Section(
+        title="Blueprint",
+        sub_title="Views",
+        mod_path="rerun.blueprint.views",
+        show_tables=False,
+    ),
     ################################################################################
     # Remaining sections
     Section(