From 1aa3427539f7cdc69ac36258031489eb1a9f67d0 Mon Sep 17 00:00:00 2001 From: Andreas Reich Date: Mon, 9 Dec 2024 16:27:05 +0100 Subject: [PATCH] Fix various doc links in SDKs (#8331) PR title is an accompanying changelog entry, but the real thing here is all about codegen fixes: * use `reporter` for doc issues * make `reporter` output colored * support field & enum links - this is a bit limited depending on the language. Experimented a bit, but deemed this now good enough. We don't use those often anyways * fix links * disable warnings for python autogen serialization being available when a custom one is present - in all cases we have the custom serialization there for a good reason or aren't entirely sure if it would break something --- Cargo.lock | 1 + Cargo.toml | 1 + crates/build/re_types_builder/Cargo.toml | 1 + .../src/codegen/cpp/method.rs | 10 +- .../re_types_builder/src/codegen/cpp/mod.rs | 58 ++-- .../re_types_builder/src/codegen/docs/mod.rs | 24 +- .../src/codegen/python/mod.rs | 35 ++- .../src/codegen/python/views.rs | 2 +- .../re_types_builder/src/codegen/rust/api.rs | 2 +- .../re_types_builder/src/codegen/rust/util.rs | 2 +- crates/build/re_types_builder/src/docs.rs | 286 +++++++++++++++--- crates/build/re_types_builder/src/objects.rs | 8 +- crates/build/re_types_builder/src/report.rs | 36 ++- .../rerun/archetypes/graph_edges.fbs | 2 +- .../rerun/blueprint/archetypes/background.fbs | 3 +- .../archetypes/container_blueprint.fbs | 10 +- .../components/visualizer_overrides.fbs | 23 -- .../rerun/components/fill_mode.fbs | 4 +- .../rerun/datatypes/pixel_format.fbs | 2 +- .../re_types/src/archetypes/graph_edges.rs | 4 +- .../src/blueprint/archetypes/background.rs | 4 +- .../re_types/src/components/fill_mode.rs | 8 +- .../src/components/transform_relation.rs | 4 +- .../re_types/src/datatypes/pixel_format.rs | 8 +- .../archetypes/container_blueprint.rs | 20 +- .../components/visualizer_overrides.rs | 23 -- crates/viewer/re_viewer/src/reflection/mod.rs | 12 +- .../reference/types/components/fill_mode.md | 4 +- .../reference/types/datatypes/pixel_format.md | 2 +- .../reference/types/views/spatial2d_view.md | 2 +- .../reference/types/views/spatial3d_view.md | 2 +- .../src/rerun/archetypes/graph_edges.hpp | 4 +- .../rerun/blueprint/archetypes/background.hpp | 4 +- .../archetypes/container_blueprint.hpp | 20 +- .../components/visualizer_overrides.hpp | 23 -- rerun_cpp/src/rerun/components/fill_mode.hpp | 4 +- .../src/rerun/datatypes/pixel_format.hpp | 2 +- .../rerun_sdk/rerun/archetypes/graph_edges.py | 4 +- .../rerun/blueprint/archetypes/background.py | 2 +- .../archetypes/container_blueprint.py | 20 +- .../rerun_sdk/rerun/components/fill_mode.py | 4 +- .../rerun_sdk/rerun/datatypes/pixel_format.py | 2 +- 42 files changed, 443 insertions(+), 249 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 43fd11e10b84..cba234963c38 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -6679,6 +6679,7 @@ dependencies = [ "arrow", "camino", "clang-format", + "colored", "flatbuffers", "indent", "itertools 0.13.0", diff --git a/Cargo.toml b/Cargo.toml index 3a0ad88ae8cd..ab7e374f6c69 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -176,6 +176,7 @@ cfg-if = "1.0" clang-format = "0.3" clap = "4.0" clean-path = "0.2" +colored = "2.1" comfy-table = { version = "7.0", default-features = false } console_error_panic_hook = "0.1.6" convert_case = "0.6" diff --git a/crates/build/re_types_builder/Cargo.toml b/crates/build/re_types_builder/Cargo.toml index 088c7ba16473..c14049d90f1e 100644 --- a/crates/build/re_types_builder/Cargo.toml +++ b/crates/build/re_types_builder/Cargo.toml @@ -38,6 +38,7 @@ arrow.workspace = true arrow2 = { workspace = true, features = ["arrow"] } camino.workspace = true clang-format.workspace = true +colored.workspace = true flatbuffers.workspace = true indent.workspace = true itertools.workspace = true diff --git a/crates/build/re_types_builder/src/codegen/cpp/method.rs b/crates/build/re_types_builder/src/codegen/cpp/method.rs index 3994f52de4ab..b54beb419654 100644 --- a/crates/build/re_types_builder/src/codegen/cpp/method.rs +++ b/crates/build/re_types_builder/src/codegen/cpp/method.rs @@ -1,7 +1,7 @@ use proc_macro2::TokenStream; use quote::quote; -use crate::{Docs, Objects}; +use crate::{Docs, Objects, Reporter}; use super::{lines_from_docs, quote_doc_comment, quote_doc_lines, NEWLINE_TOKEN}; @@ -78,14 +78,14 @@ impl From<&str> for MethodDocumentation { } impl MethodDocumentation { - fn quoted(&self, objects: &Objects) -> TokenStream { + fn quoted(&self, reporter: &Reporter, objects: &Objects) -> TokenStream { match self { Self::None => { quote!() } Self::String(s) => quote_doc_comment(s), Self::Docs(docs) => { - let lines = lines_from_docs(objects, docs); + let lines = lines_from_docs(reporter, objects, docs); quote_doc_lines(&lines) } } @@ -112,7 +112,7 @@ impl Default for Method { } impl Method { - pub fn to_hpp_tokens(&self, objects: &Objects) -> TokenStream { + pub fn to_hpp_tokens(&self, reporter: &Reporter, objects: &Objects) -> TokenStream { let Self { docs, declaration, @@ -120,7 +120,7 @@ impl Method { inline: is_inline, } = self; - let docs = docs.quoted(objects); + let docs = docs.quoted(reporter, objects); let declaration = declaration.to_hpp_tokens(); if *is_inline { quote! { diff --git a/crates/build/re_types_builder/src/codegen/cpp/mod.rs b/crates/build/re_types_builder/src/codegen/cpp/mod.rs index a1c3a0d98935..dd41590729a6 100644 --- a/crates/build/re_types_builder/src/codegen/cpp/mod.rs +++ b/crates/build/re_types_builder/src/codegen/cpp/mod.rs @@ -409,12 +409,14 @@ impl QuotedObject { match obj.class { ObjectClass::Struct => match obj.kind { ObjectKind::Datatype | ObjectKind::Component => Ok(Self::from_struct( + reporter, objects, obj, hpp_includes, hpp_type_extensions, )), ObjectKind::Archetype => Ok(Self::from_archetype( + reporter, objects, obj, hpp_includes, @@ -429,9 +431,10 @@ impl QuotedObject { if !hpp_type_extensions.is_empty() { reporter.error(&obj.virtpath, &obj.fqname, "C++ enums cannot have type extensions, because C++ enums doesn't support member functions"); } - Ok(Self::from_enum(objects, obj, hpp_includes)) + Ok(Self::from_enum(reporter, objects, obj, hpp_includes)) } ObjectClass::Union => Ok(Self::from_union( + reporter, objects, obj, hpp_includes, @@ -441,13 +444,14 @@ impl QuotedObject { } fn from_archetype( + reporter: &Reporter, objects: &Objects, obj: &Object, mut hpp_includes: Includes, hpp_type_extensions: &TokenStream, ) -> Self { let type_ident = obj.ident(); - let quoted_docs = quote_obj_docs(objects, obj); + let quoted_docs = quote_obj_docs(reporter, objects, obj); let mut cpp_includes = Includes::new(obj.fqname.clone(), obj.scope()); cpp_includes.insert_rerun("collection_adapter_builtins.hpp"); @@ -458,7 +462,7 @@ impl QuotedObject { .fields .iter() .map(|obj_field| { - let docstring = quote_field_docs(objects, obj_field); + let docstring = quote_field_docs(reporter, objects, obj_field); let field_name = field_name_identifier(obj_field); let field_type = quote_archetype_field_type(&mut hpp_includes, obj_field); let field_type = if obj_field.is_nullable { @@ -549,11 +553,11 @@ impl QuotedObject { }; let serialize_method = archetype_serialize(&type_ident, obj, &mut hpp_includes); - let serialize_hpp = serialize_method.to_hpp_tokens(objects); + let serialize_hpp = serialize_method.to_hpp_tokens(reporter, objects); let serialize_cpp = serialize_method.to_cpp_tokens("e!(AsComponents<#quoted_namespace::#type_ident>)); - let methods_hpp = methods.iter().map(|m| m.to_hpp_tokens(objects)); + let methods_hpp = methods.iter().map(|m| m.to_hpp_tokens(reporter, objects)); let methods_cpp = methods .iter() .map(|m| m.to_cpp_tokens("e!(#type_ident))); @@ -648,6 +652,7 @@ impl QuotedObject { } fn from_struct( + reporter: &Reporter, objects: &Objects, obj: &Object, mut hpp_includes: Includes, @@ -663,7 +668,7 @@ impl QuotedObject { }; let type_ident = obj.ident(); - let quoted_docs = quote_obj_docs(objects, obj); + let quoted_docs = quote_obj_docs(reporter, objects, obj); let deprecation_notice = quote_deprecation_notice(obj); let mut cpp_includes = Includes::new(obj.fqname.clone(), obj.scope()); @@ -674,6 +679,7 @@ impl QuotedObject { .iter() .map(|obj_field| { let declaration = quote_variable_with_docstring( + reporter, objects, &mut hpp_includes, obj_field, @@ -721,9 +727,10 @@ impl QuotedObject { } } - let methods_hpp = methods.iter().map(|m| m.to_hpp_tokens(objects)); + let methods_hpp = methods.iter().map(|m| m.to_hpp_tokens(reporter, objects)); let (hpp_loggable, cpp_loggable) = quote_loggable_hpp_and_cpp( + reporter, obj, objects, &mut hpp_includes, @@ -776,6 +783,7 @@ impl QuotedObject { } fn from_union( + reporter: &Reporter, objects: &Objects, obj: &Object, mut hpp_includes: Includes, @@ -815,7 +823,7 @@ impl QuotedObject { let pascal_case_name = &obj.name; let pascal_case_ident = obj.ident(); - let quoted_docs = quote_obj_docs(objects, obj); + let quoted_docs = quote_obj_docs(reporter, objects, obj); let deprecation_notice = quote_deprecation_notice(obj); let tag_typename = format_ident!("{pascal_case_name}Tag"); @@ -853,6 +861,7 @@ impl QuotedObject { .filter(|obj_field| obj_field.typ != Type::Unit) .map(|obj_field| { let declaration = quote_variable_with_docstring( + reporter, objects, &mut hpp_includes, obj_field, @@ -1092,6 +1101,7 @@ impl QuotedObject { let hide_from_docs_comment = quote_hide_from_docs(); let (hpp_loggable, cpp_loggable) = quote_loggable_hpp_and_cpp( + reporter, obj, objects, &mut hpp_includes, @@ -1099,7 +1109,7 @@ impl QuotedObject { &mut hpp_declarations, ); - let methods_hpp = methods.iter().map(|m| m.to_hpp_tokens(objects)); + let methods_hpp = methods.iter().map(|m| m.to_hpp_tokens(reporter, objects)); let hpp = quote! { #hpp_includes @@ -1211,7 +1221,12 @@ impl QuotedObject { } // C-style enum - fn from_enum(objects: &Objects, obj: &Object, mut hpp_includes: Includes) -> Self { + fn from_enum( + reporter: &Reporter, + objects: &Objects, + obj: &Object, + mut hpp_includes: Includes, + ) -> Self { // We use a simple `enum class`, which is a type-safe enum. // They don't support methods, but we don't need them, // since `Loggable` is implemented outside the type. @@ -1226,7 +1241,7 @@ impl QuotedObject { }; let type_ident = obj.ident(); - let quoted_docs = quote_obj_docs(objects, obj); + let quoted_docs = quote_obj_docs(reporter, objects, obj); let deprecation_notice = quote_deprecation_notice(obj); let mut cpp_includes = Includes::new(obj.fqname.clone(), obj.scope()); @@ -1237,7 +1252,7 @@ impl QuotedObject { .iter() .map(|obj_field| { let enum_value = obj_field.enum_value.unwrap(); - let docstring = quote_field_docs(objects, obj_field); + let docstring = quote_field_docs(reporter, objects, obj_field); let field_name = field_name_identifier(obj_field); // We assign the arrow type index to the enum fields to make encoding simpler and faster: @@ -1252,6 +1267,7 @@ impl QuotedObject { .collect_vec(); let (hpp_loggable, cpp_loggable) = quote_loggable_hpp_and_cpp( + reporter, obj, objects, &mut hpp_includes, @@ -2201,6 +2217,7 @@ fn quote_archetype_field_type(hpp_includes: &mut Includes, obj_field: &ObjectFie } fn quote_variable_with_docstring( + reporter: &Reporter, objects: &Objects, includes: &mut Includes, obj_field: &ObjectField, @@ -2208,7 +2225,7 @@ fn quote_variable_with_docstring( ) -> TokenStream { let quoted = quote_variable(includes, obj_field, name); - let docstring = quote_field_docs(objects, obj_field); + let docstring = quote_field_docs(reporter, objects, obj_field); let quoted = quote! { #docstring @@ -2318,8 +2335,8 @@ fn quote_fqname_as_type_path(includes: &mut Includes, fqname: &str) -> TokenStre quote!(#expr) } -fn quote_obj_docs(objects: &Objects, obj: &Object) -> TokenStream { - let mut lines = lines_from_docs(objects, &obj.docs); +fn quote_obj_docs(reporter: &Reporter, objects: &Objects, obj: &Object) -> TokenStream { + let mut lines = lines_from_docs(reporter, objects, &obj.docs); if let Some(first_line) = lines.first_mut() { // Prefix with object kind: @@ -2336,13 +2353,13 @@ fn quote_obj_docs(objects: &Objects, obj: &Object) -> TokenStream { quote_doc_lines(&lines) } -fn quote_field_docs(objects: &Objects, field: &ObjectField) -> TokenStream { - let lines = lines_from_docs(objects, &field.docs); +fn quote_field_docs(reporter: &Reporter, objects: &Objects, field: &ObjectField) -> TokenStream { + let lines = lines_from_docs(reporter, objects, &field.docs); quote_doc_lines(&lines) } -fn lines_from_docs(objects: &Objects, docs: &Docs) -> Vec { - let mut lines = docs.lines_for(objects, Target::Cpp); +fn lines_from_docs(reporter: &Reporter, objects: &Objects, docs: &Docs) -> Vec { + let mut lines = docs.lines_for(reporter, objects, Target::Cpp); let required = true; let examples = collect_snippets_for_api_docs(docs, "cpp", required).unwrap_or_default(); @@ -2515,6 +2532,7 @@ fn quote_arrow_elem_type( } fn quote_loggable_hpp_and_cpp( + reporter: &Reporter, obj: &Object, objects: &Objects, hpp_includes: &mut Includes, @@ -2567,7 +2585,7 @@ fn quote_loggable_hpp_and_cpp( } }; - let methods_hpp = methods.iter().map(|m| m.to_hpp_tokens(objects)); + let methods_hpp = methods.iter().map(|m| m.to_hpp_tokens(reporter, objects)); let methods_cpp = methods.iter().map(|m| m.to_cpp_tokens(&loggable_type_name)); let hide_from_docs_comment = quote_hide_from_docs(); diff --git a/crates/build/re_types_builder/src/codegen/docs/mod.rs b/crates/build/re_types_builder/src/codegen/docs/mod.rs index 2deb26b120d6..b2ca29c0174f 100644 --- a/crates/build/re_types_builder/src/codegen/docs/mod.rs +++ b/crates/build/re_types_builder/src/codegen/docs/mod.rs @@ -123,7 +123,7 @@ on [Entities and Components](../../concepts/entity-component.md).", &views, ), ] { - let page = index_page(objects, kind, order, prelude, kind_objects); + let page = index_page(reporter, objects, kind, order, prelude, kind_objects); let path = self .docs_dir .join(format!("{}.md", kind.plural_snake_case())); @@ -146,6 +146,7 @@ fn collect_view_types_per_archetype(objects: &Objects) -> ViewsPerArchetype { } fn index_page( + reporter: &Reporter, all_objects: &Objects, kind: ObjectKind, order: u64, @@ -203,7 +204,7 @@ fn index_page( object.snake_case_name(), object .docs - .first_line(all_objects, Target::WebDocsMarkdown) + .first_line(reporter, all_objects, Target::WebDocsMarkdown) .unwrap_or_default(), ); } @@ -223,7 +224,9 @@ fn object_page( let is_unreleased = object.is_attr_set(crate::ATTR_DOCS_UNRELEASED); let is_experimental = object.is_experimental(); - let top_level_docs = object.docs.lines_for(objects, Target::WebDocsMarkdown); + let top_level_docs = object + .docs + .lines_for(reporter, objects, Target::WebDocsMarkdown); if top_level_docs.is_empty() { reporter.error(&object.virtpath, &object.fqname, "Undocumented object"); @@ -271,7 +274,7 @@ fn object_page( match object.kind { ObjectKind::Datatype | ObjectKind::Component => { - write_fields(objects, &mut page, object); + write_fields(reporter, objects, &mut page, object); } ObjectKind::Archetype => { write_archetype_fields(objects, &mut page, object, views_per_archetype); @@ -402,7 +405,7 @@ fn write_frontmatter(o: &mut String, title: &str, order: Option) { putln!(o, "", autogen_warning!()); } -fn write_fields(objects: &Objects, o: &mut String, object: &Object) { +fn write_fields(reporter: &Reporter, objects: &Objects, o: &mut String, object: &Object) { if object.fields.is_empty() { return; } @@ -491,7 +494,10 @@ fn write_fields(objects: &Objects, o: &mut String, object: &Object) { field_string.push('\n'); } - for line in field.docs.lines_for(objects, Target::WebDocsMarkdown) { + for line in field + .docs + .lines_for(reporter, objects, Target::WebDocsMarkdown) + { field_string.push_str(&line); field_string.push('\n'); } @@ -705,7 +711,9 @@ fn write_view_property( ) { putln!(o, "### `{}`", field.name); - let top_level_docs = field.docs.lines_for(objects, Target::WebDocsMarkdown); + let top_level_docs = field + .docs + .lines_for(reporter, objects, Target::WebDocsMarkdown); if top_level_docs.is_empty() { reporter.error(&field.virtpath, &field.fqname, "Undocumented view property"); @@ -728,7 +736,7 @@ fn write_view_property( field.name, field .docs - .first_line(objects, Target::WebDocsMarkdown) + .first_line(reporter, objects, Target::WebDocsMarkdown) .unwrap_or_default() )); } diff --git a/crates/build/re_types_builder/src/codegen/python/mod.rs b/crates/build/re_types_builder/src/codegen/python/mod.rs index 6688257bc230..1b0eeb135435 100644 --- a/crates/build/re_types_builder/src/codegen/python/mod.rs +++ b/crates/build/re_types_builder/src/codegen/python/mod.rs @@ -1110,7 +1110,7 @@ fn code_for_union( format!("inner: {inner_type} = field({converter} {type_ignore}\n)"), 1, ); - code.push_indented(1, quote_doc_from_fields(objects, fields), 0); + code.push_indented(1, quote_doc_from_fields(reporter, objects, fields), 0); // if there are duplicate types, we need to add a `kind` field to disambiguate the union if has_duplicate_types { @@ -1126,7 +1126,11 @@ fn code_for_union( 1, ); - code.push_indented(1, quote_union_kind_from_fields(objects, fields), 0); + code.push_indented( + 1, + quote_union_kind_from_fields(reporter, objects, fields), + 0, + ); } code.push_unindented(quote_union_aliases_from_object(obj, field_types.iter()), 1); @@ -1241,7 +1245,7 @@ fn lines_from_docs( docs: &Docs, is_experimental: bool, ) -> Vec { - let mut lines = docs.lines_for(objects, Target::Python); + let mut lines = docs.lines_for(reporter, objects, Target::Python); if is_experimental { lines.push(String::new()); @@ -1299,11 +1303,15 @@ fn quote_doc_lines(lines: Vec) -> String { } } -fn quote_doc_from_fields(objects: &Objects, fields: &Vec) -> String { +fn quote_doc_from_fields( + reporter: &Reporter, + objects: &Objects, + fields: &Vec, +) -> String { let mut lines = vec!["Must be one of:".to_owned(), String::new()]; for field in fields { - let mut content = field.docs.lines_for(objects, Target::Python); + let mut content = field.docs.lines_for(reporter, objects, Target::Python); for line in &mut content { if line.starts_with(char::is_whitespace) { line.remove(0); @@ -1341,11 +1349,15 @@ fn quote_doc_from_fields(objects: &Objects, fields: &Vec) -> String format!("\"\"\"\n{doc}\n\"\"\"\n\n") } -fn quote_union_kind_from_fields(objects: &Objects, fields: &Vec) -> String { +fn quote_union_kind_from_fields( + reporter: &Reporter, + objects: &Objects, + fields: &Vec, +) -> String { let mut lines = vec!["Possible values:".to_owned(), String::new()]; for field in fields { - let mut content = field.docs.lines_for(objects, Target::Python); + let mut content = field.docs.lines_for(reporter, objects, Target::Python); for line in &mut content { if line.starts_with(char::is_whitespace) { line.remove(0); @@ -1878,7 +1890,12 @@ fn quote_arrow_support_from_obj( ) { Ok(automatic_arrow_serialization) => { if ext_class.has_native_to_pa_array { - reporter.warn(&obj.virtpath, &obj.fqname, format!("No need to manually implement {NATIVE_TO_PA_ARRAY_METHOD} in {} - we can autogenerate the code for this", ext_class.file_name)); + // There's usually a good reason why serialization is manually implemented, + // so warning about it is just spam. + // We could introduce an opt-in flag, but by having a custom method in the first place someone already made the choice. + if false { + reporter.warn(&obj.virtpath, &obj.fqname, format!("No need to manually implement {NATIVE_TO_PA_ARRAY_METHOD} in {} - we can autogenerate the code for this", ext_class.file_name)); + } format!( "return {}.{NATIVE_TO_PA_ARRAY_METHOD}(data, data_type)", ext_class.name @@ -2378,7 +2395,7 @@ fn quote_init_method( obj.fields .iter() .filter_map(|field| { - let doc_content = field.docs.lines_for(objects, Target::Python); + let doc_content = field.docs.lines_for(reporter, objects, Target::Python); if doc_content.is_empty() { if !field.is_testing() && obj.fields.len() > 1 { reporter.error( diff --git a/crates/build/re_types_builder/src/codegen/python/views.rs b/crates/build/re_types_builder/src/codegen/python/views.rs index cc06d29ea9e2..1f464d99cc3c 100644 --- a/crates/build/re_types_builder/src/codegen/python/views.rs +++ b/crates/build/re_types_builder/src/codegen/python/views.rs @@ -144,7 +144,7 @@ do not yet support `$origin` relative paths or glob expressions. This will be addressed in .".to_owned(),) ]; for field in &obj.fields { - let doc_content = field.docs.lines_for(objects, Target::Python); + let doc_content = field.docs.lines_for(reporter, objects, Target::Python); if doc_content.is_empty() { reporter.error( &field.virtpath, diff --git a/crates/build/re_types_builder/src/codegen/rust/api.rs b/crates/build/re_types_builder/src/codegen/rust/api.rs index 24bf5d4188a2..3125197d0889 100644 --- a/crates/build/re_types_builder/src/codegen/rust/api.rs +++ b/crates/build/re_types_builder/src/codegen/rust/api.rs @@ -580,7 +580,7 @@ fn quote_enum( &field.virtpath, &field.fqname, &field.docs, - Target::Rust, + Target::WebDocsMarkdown, false, ) .join("\n"); diff --git a/crates/build/re_types_builder/src/codegen/rust/util.rs b/crates/build/re_types_builder/src/codegen/rust/util.rs index eb3e41a2661a..671b3a31b161 100644 --- a/crates/build/re_types_builder/src/codegen/rust/util.rs +++ b/crates/build/re_types_builder/src/codegen/rust/util.rs @@ -300,7 +300,7 @@ pub fn doc_as_lines( target: Target, is_experimental: bool, ) -> Vec { - let mut lines = docs.lines_for(objects, target); + let mut lines = docs.lines_for(reporter, objects, target); if is_experimental { lines.push(String::new()); diff --git a/crates/build/re_types_builder/src/docs.rs b/crates/build/re_types_builder/src/docs.rs index 3f9084d09a5a..52d8a3c20166 100644 --- a/crates/build/re_types_builder/src/docs.rs +++ b/crates/build/re_types_builder/src/docs.rs @@ -1,7 +1,7 @@ -use crate::{codegen::Target, Objects}; +use crate::{codegen::Target, Objects, Reporter}; /// A high-level representation of the contents of a flatbuffer docstring. -#[derive(Debug, Clone)] +#[derive(Debug, Clone, Default)] pub struct Docs { /// All docmentation lines, including the leading tag, if any. /// @@ -15,19 +15,32 @@ pub struct Docs { impl Docs { pub fn from_raw_docs( + reporter: &Reporter, + virtpath: &str, + fqname: &str, docs: Option>>, ) -> Self { - Self::from_lines(docs.into_iter().flat_map(|doc| doc.into_iter())) + Self::from_lines( + reporter, + virtpath, + fqname, + docs.into_iter().flat_map(|doc| doc.into_iter()), + ) } - pub fn from_lines<'a>(lines: impl Iterator) -> Self { + pub fn from_lines<'a>( + reporter: &Reporter, + virtpath: &str, + fqname: &str, + lines: impl Iterator, + ) -> Self { let lines: Vec<(String, String)> = lines.map(parse_line).collect(); for (tag, comment) in &lines { assert!(is_known_tag(tag), "Unknown tag: '\\{tag} {comment}'"); if tag.is_empty() { - find_and_recommend_doclinks(comment); + find_and_recommend_doclinks(reporter, virtpath, fqname, comment); } } @@ -35,13 +48,18 @@ impl Docs { } /// Get the first line of the documentation untagged. - pub fn first_line(&self, objects: &Objects, target: Target) -> Option { + pub fn first_line( + &self, + reporter: &Reporter, + objects: &Objects, + target: Target, + ) -> Option { let (tag, line) = self.lines.first()?; assert!( tag.is_empty(), "Expected no tag on first line of docstring. Found: /// \\{tag} {line}" ); - Some(translate_doc_line(objects, line, target)) + Some(translate_doc_line(reporter, objects, line, target)) } /// Get all doc lines that start with the given tag. @@ -68,7 +86,12 @@ impl Docs { /// For instance, pass [`Target::Python`] to get all lines that are untagged or starts with `"\py"`. /// /// The tagged lines (`\py`) are left as is, but untagged lines will have Rerun doclinks translated to the target language. - pub(super) fn lines_for(&self, objects: &Objects, target: Target) -> Vec { + pub(super) fn lines_for( + &self, + reporter: &Reporter, + objects: &Objects, + target: Target, + ) -> Vec { let target_tag = match target { Target::Cpp => "cpp", Target::Python => "py", @@ -82,7 +105,7 @@ impl Docs { remove_extra_newlines(self.lines.iter().filter_map(|(tag, line)| { if tag.is_empty() { - Some(translate_doc_line(objects, line, target)) + Some(translate_doc_line(reporter, objects, line, target)) } else if tag == target_tag { // We don't expect doclinks in tagged lines, because tagged lines are usually // language-specific, and thus should have the correct format already. @@ -144,7 +167,12 @@ fn parse_line(line: &str) -> (String, String) { } /// Look for things that look like doclinks to other types, but aren't in brackets. -fn find_and_recommend_doclinks(full_comment: &str) { +fn find_and_recommend_doclinks( + reporter: &Reporter, + virtpath: &str, + fqname: &str, + full_comment: &str, +) { let mut comment = full_comment; while let Some(start) = comment.find('`') { comment = &comment[start + 1..]; @@ -161,11 +189,11 @@ fn find_and_recommend_doclinks(full_comment: &str) { // In some blueprint code we refer to stuff in Rerun. && !matches!(content, "ChunkStore" | "ContainerId" | "EntityPathFilter" | "Spatial2DView" | "SpaceViewId" | "SpaceView") - // TODO(emilk): allow doclinks to enum variants. - && !matches!(content, "Horizontal" | "Vertical" | "SolidColor"); + // Doc links to OpenStreetMap may show up + && !matches!(content, "OpenStreetMap"); if looks_like_type_name { - re_log::warn!("`{content}` can be written as a doclink, e.g. [archetypes.{content}] in comment: /// {full_comment}"); + reporter.warn(virtpath, fqname, format!("`{content}` can be written as a doclink, e.g. [archetypes.{content}] in comment: /// {full_comment}")); } comment = &comment[end + 1..]; } else { @@ -188,12 +216,17 @@ use doclink_translation::translate_doc_line; /// /// The code is not very efficient, but it is simple and works. mod doclink_translation { - use crate::Objects; + use crate::{ObjectKind, Objects, Reporter}; use super::Target; /// Convert Rerun-style doclinks to the target language. - pub fn translate_doc_line(objects: &Objects, input: &str, target: Target) -> String { + pub fn translate_doc_line( + reporter: &Reporter, + objects: &Objects, + input: &str, + target: Target, + ) -> String { let mut out_tokens: Vec = vec![]; let mut within_backticks = false; @@ -230,7 +263,12 @@ mod doclink_translation { continue; } - out_tokens.push(translate_doclink(objects, &doclink_tokens, target)); + out_tokens.push(translate_doclink( + reporter, + objects, + &doclink_tokens, + target, + )); continue; } @@ -241,7 +279,12 @@ mod doclink_translation { out_tokens.into_iter().collect() } - fn translate_doclink(objects: &Objects, doclink_tokens: &[&str], target: Target) -> String { + fn translate_doclink( + reporter: &Reporter, + objects: &Objects, + doclink_tokens: &[&str], + target: Target, + ) -> String { try_translate_doclink(objects, doclink_tokens, target).unwrap_or_else(|err| { let original_doclink: String = doclink_tokens.join(""); @@ -250,9 +293,9 @@ mod doclink_translation { !original_doclink.contains(' ') && original_doclink.len() > 6; if looks_like_rerun_doclink { - re_log::warn_once!( + reporter.warn_no_context(format!( "Looks like a Rerun doclink, but fails to parse: {original_doclink} - {err}" - ); + )); } original_doclink @@ -263,29 +306,53 @@ mod doclink_translation { objects: &Objects, doclink_tokens: &[&str], target: Target, - ) -> Result { + ) -> Result { + let has_type_or_enum = doclink_tokens.iter().filter(|t| t == &&".").count() == 2; + let mut tokens = doclink_tokens.iter(); if tokens.next() != Some(&"[") { - return Err("Missing opening bracket"); + return Err("Missing opening bracket".to_owned()); } let kind = *tokens.next().ok_or("Missing kind")?; if kind == "`" { - return Err("Do not use backticks inside doclinks"); + return Err("Do not use backticks inside doclinks".to_owned()); } if tokens.next() != Some(&".") { - return Err("Missing dot"); + return Err("Missing dot".to_owned()); } let type_name = *tokens.next().ok_or("Missing type name")?; + + let field_or_enum_name = if has_type_or_enum { + if tokens.next() != Some(&".") { + return Err("Missing dot".to_owned()); + } + tokens.next() + } else { + None + }; + if tokens.next() != Some(&"]") { - return Err("Missing closing bracket"); + return Err("Missing closing bracket".to_owned()); } if tokens.next().is_some() { - return Err("Trailing tokens"); + return Err("Trailing tokens".to_owned()); } - // TODO(emilk): support links to fields and enum variants + // Validate kind: + if ObjectKind::ALL + .iter() + .all(|object_kind| object_kind.plural_snake_case() != kind) + { + return Err(format!( + "Invalid kind {kind:?}. Valid are: {}", + ObjectKind::ALL + .map(|object_kind| object_kind.plural_snake_case()) + .join(", ") + )); + } - let mut is_unreleased = false; + let is_unreleased; + let scope; { // Find the target object: let mut candidates = vec![]; @@ -294,30 +361,61 @@ mod doclink_translation { candidates.push(obj); } } - if candidates.is_empty() { - // NOTE: we don't error if the target doesn't exists. - // Instead we rely on the documentation tools for the different targets, - // e.g. `cargo doc` and our url link checker. - // Maybe we could change that though to catch errors earlier. - re_log::warn_once!("No object found for doclink: [{kind}.{type_name}]"); - } else if candidates.len() > 2 { + + let Some(object) = candidates.first() else { + return Err("No object found for doclink".to_owned()); + }; + + if candidates.len() > 2 { use itertools::Itertools as _; - re_log::warn_once!( - "Multiple objects found for doclink: [{kind}.{type_name}]: {}", + return Err(format!( + "Multiple objects found for doclink: {}", candidates.iter().map(|obj| &obj.fqname).format(", ") - ); - } else if let Some(object) = candidates.first() { - is_unreleased = object.is_attr_set(crate::ATTR_DOCS_UNRELEASED); + )); } + + scope = object.scope().unwrap_or_default(); + is_unreleased = object.is_attr_set(crate::ATTR_DOCS_UNRELEASED); } Ok(match target { - Target::Cpp => format!("`{kind}::{type_name}`"), + Target::Cpp => { + if let Some(field_or_enum_name) = field_or_enum_name { + format!("`{kind}::{type_name}::{field_or_enum_name}`") + } else { + format!("`{kind}::{type_name}`") + } + } Target::Rust => { // https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html - format!("[`{kind}::{type_name}`][crate::{kind}::{type_name}]") + let kind_and_type = format!("{kind}::{type_name}"); + let object_path = if scope.is_empty() { + kind_and_type.clone() + } else { + format!("{scope}::{kind_and_type}") + }; + + if let Some(field_or_enum_name) = field_or_enum_name { + format!( + "[`{kind_and_type}::{field_or_enum_name}`][crate::{object_path}::{field_or_enum_name}]" + ) + } else { + format!("[`{kind_and_type}`][crate::{object_path}]") + } + } + Target::Python => { + let kind_and_type = format!("{kind}.{type_name}"); + let object_path = if scope.is_empty() { + format!("rerun.{kind_and_type}") + } else { + format!("rerun.{scope}.{kind_and_type}") + }; + if let Some(field_or_enum_name) = field_or_enum_name { + format!("[`{kind_and_type}.{field_or_enum_name}`][{object_path}.{field_or_enum_name}]") + } else { + format!("[`{kind_and_type}`][{object_path}]") + } } - Target::Python => format!("[`{kind}.{type_name}`][rerun.{kind}.{type_name}]"), Target::WebDocsMarkdown => { // For instance, https://rerun.io/docs/reference/types/views/spatial2d_view // TODO(emilk): relative links would be nicer for the local markdown files @@ -327,7 +425,15 @@ mod doclink_translation { } else { "" }; - format!("[`{kind}.{type_name}`](https://rerun.io/docs/reference/types/{kind}/{type_name_snake_case}{query})") + + let url = format!( + "https://rerun.io/docs/reference/types/{kind}/{type_name_snake_case}{query}" + ); + if let Some(field_or_enum_name) = field_or_enum_name { + format!("[`{kind}.{type_name}#{field_or_enum_name}`]({url})") + } else { + format!("[`{kind}.{type_name}`]({url})") + } } }) } @@ -355,8 +461,32 @@ mod doclink_translation { #[cfg(test)] mod tests { + use crate::{Attributes, Docs, Object, Objects}; + use super::*; + fn test_objects() -> Objects { + Objects { + objects: std::iter::once(( + "rerun.views.Spatial2DView".to_owned(), + Object { + virtpath: "path".to_owned(), + filepath: "path".into(), + fqname: "rerun.views.Spatial2DView".to_owned(), + pkg_name: "test".to_owned(), + name: "Spatial2DView".to_owned(), + docs: Docs::default(), + kind: ObjectKind::View, + attrs: Attributes::default(), + fields: Vec::new(), + class: crate::ObjectClass::Struct, + datatype: None, + }, + )) + .collect(), + } + } + #[test] fn test_tokenize() { assert_eq!(tokenize("This is a comment"), vec!["This is a comment"]); @@ -382,13 +512,15 @@ mod doclink_translation { #[test] fn test_translate_doclinks() { - let objects = Objects::default(); + let objects = test_objects(); + let (_report, reporter) = crate::report::init(); let input = "A vector `[1, 2, 3]` and a doclink [views.Spatial2DView] and a [url](www.rerun.io)."; assert_eq!( translate_doc_line( + &reporter, &objects, input, Target::Cpp @@ -398,24 +530,27 @@ mod doclink_translation { assert_eq!( translate_doc_line( + &reporter, &objects, input, Target::Python ), - "A vector `[1, 2, 3]` and a doclink [`views.Spatial2DView`][rerun.views.Spatial2DView] and a [url](www.rerun.io)." + "A vector `[1, 2, 3]` and a doclink [`views.Spatial2DView`][rerun.blueprint.views.Spatial2DView] and a [url](www.rerun.io)." ); assert_eq!( translate_doc_line( + &reporter, &objects, input, Target::Rust ), - "A vector `[1, 2, 3]` and a doclink [`views::Spatial2DView`][crate::views::Spatial2DView] and a [url](www.rerun.io)." + "A vector `[1, 2, 3]` and a doclink [`views::Spatial2DView`][crate::blueprint::views::Spatial2DView] and a [url](www.rerun.io)." ); assert_eq!( translate_doc_line( + &reporter, &objects, input, Target::WebDocsMarkdown @@ -423,6 +558,55 @@ mod doclink_translation { "A vector `[1, 2, 3]` and a doclink [`views.Spatial2DView`](https://rerun.io/docs/reference/types/views/spatial2d_view) and a [url](www.rerun.io)." ); } + + #[test] + fn test_translate_doclinks_with_field() { + let objects = test_objects(); + let (_report, reporter) = crate::report::init(); + + let input = + "A vector `[1, 2, 3]` and a doclink [views.Spatial2DView.position] and a [url](www.rerun.io)."; + + assert_eq!( + translate_doc_line( + &reporter, + &objects, + input, + Target::Cpp + ), + "A vector `[1, 2, 3]` and a doclink `views::Spatial2DView::position` and a [url](www.rerun.io)." + ); + + assert_eq!( + translate_doc_line( + &reporter, + &objects, + input, + Target::Python + ), + "A vector `[1, 2, 3]` and a doclink [`views.Spatial2DView.position`][rerun.blueprint.views.Spatial2DView.position] and a [url](www.rerun.io)." + ); + + assert_eq!( + translate_doc_line( + &reporter, + &objects, + input, + Target::Rust + ), + "A vector `[1, 2, 3]` and a doclink [`views::Spatial2DView::position`][crate::blueprint::views::Spatial2DView::position] and a [url](www.rerun.io)." + ); + + assert_eq!( + translate_doc_line( + &reporter, + &objects, + input, + Target::WebDocsMarkdown + ), + "A vector `[1, 2, 3]` and a doclink [`views.Spatial2DView#position`](https://rerun.io/docs/reference/types/views/spatial2d_view) and a [url](www.rerun.io)." + ); + } } } @@ -434,8 +618,12 @@ mod tests { #[test] fn test_docs() { let objects = Objects::default(); + let (_report, reporter) = crate::report::init(); let docs = Docs::from_lines( + &reporter, + "testpath", + "testfqname", [ r" Doclink to [views.Spatial2DView].", r" ", @@ -455,7 +643,7 @@ mod tests { assert_eq!(docs.only_lines_tagged("cpp"), vec!["Only for C++.",]); assert_eq!( - docs.lines_for(&objects, Target::Python), + docs.lines_for(&reporter, &objects, Target::Python), vec![ "Doclink to [`views.Spatial2DView`][rerun.views.Spatial2DView].", "", @@ -468,7 +656,7 @@ mod tests { ); assert_eq!( - docs.lines_for(&objects, Target::Cpp), + docs.lines_for(&reporter, &objects, Target::Cpp), vec![ "Doclink to `views::Spatial2DView`.", "", @@ -481,7 +669,7 @@ mod tests { ); assert_eq!( - docs.first_line(&objects, Target::Rust), + docs.first_line(&reporter, &objects, Target::Rust), Some("Doclink to [`views::Spatial2DView`][crate::views::Spatial2DView].".to_owned()) ); } diff --git a/crates/build/re_types_builder/src/objects.rs b/crates/build/re_types_builder/src/objects.rs index 8a71b0d0cfb1..d311ba9b1100 100644 --- a/crates/build/re_types_builder/src/objects.rs +++ b/crates/build/re_types_builder/src/objects.rs @@ -391,7 +391,7 @@ impl Object { "Bad filepath: {filepath:?}" ); - let docs = Docs::from_raw_docs(obj.documentation()); + let docs = Docs::from_raw_docs(reporter, &virtpath, obj.name(), obj.documentation()); let attrs = Attributes::from_raw_attrs(obj.attributes()); let kind = ObjectKind::from_pkg_name(&pkg_name, &attrs); @@ -478,7 +478,7 @@ impl Object { .unwrap(); let filepath = filepath_from_declaration_file(include_dir_path, &virtpath); - let docs = Docs::from_raw_docs(enm.documentation()); + let docs = Docs::from_raw_docs(reporter, &virtpath, enm.name(), enm.documentation()); let attrs = Attributes::from_raw_attrs(enm.attributes()); let kind = ObjectKind::from_pkg_name(&pkg_name, &attrs); @@ -772,7 +772,7 @@ impl ObjectField { .unwrap(); let filepath = filepath_from_declaration_file(include_dir_path, &virtpath); - let docs = Docs::from_raw_docs(field.documentation()); + let docs = Docs::from_raw_docs(reporter, &virtpath, field.name(), field.documentation()); let attrs = Attributes::from_raw_attrs(field.attributes()); @@ -832,7 +832,7 @@ impl ObjectField { .unwrap(); let filepath = filepath_from_declaration_file(include_dir_path, &virtpath); - let docs = Docs::from_raw_docs(val.documentation()); + let docs = Docs::from_raw_docs(reporter, &virtpath, val.name(), val.documentation()); let attrs = Attributes::from_raw_attrs(val.attributes()); diff --git a/crates/build/re_types_builder/src/report.rs b/crates/build/re_types_builder/src/report.rs index 4f794ec4c71a..06fee4945eea 100644 --- a/crates/build/re_types_builder/src/report.rs +++ b/crates/build/re_types_builder/src/report.rs @@ -41,14 +41,27 @@ impl Reporter { #[allow(clippy::needless_pass_by_value)] // `&impl ToString` has worse usability pub fn error(&self, virtpath: &str, fqname: &str, text: impl ToString) { self.errors - .send(format!("{virtpath} {fqname}: {}", text.to_string())) + .send(format!( + "{} {fqname}: {}", + Self::format_virtpath(virtpath), + text.to_string() + )) .ok(); } + #[allow(clippy::needless_pass_by_value)] // `&impl ToString` has worse usability + pub fn warn_no_context(&self, text: impl ToString) { + self.warnings.send(text.to_string()).ok(); + } + #[allow(clippy::needless_pass_by_value)] // `&impl ToString` has worse usability pub fn warn(&self, virtpath: &str, fqname: &str, text: impl ToString) { self.warnings - .send(format!("{virtpath} {fqname}: {}", text.to_string())) + .send(format!( + "{} {fqname}: {}", + Self::format_virtpath(virtpath), + text.to_string() + )) .ok(); } @@ -56,6 +69,19 @@ impl Reporter { pub fn error_any(&self, text: impl ToString) { self.errors.send(text.to_string()).ok(); } + + // Tries to format a virtual fbs path such that it can be clicked in the CLI. + fn format_virtpath(virtpath: &str) -> String { + if let Ok(path) = Utf8Path::new(virtpath).canonicalize() { + path.display().to_string() + } else if let Ok(path) = + Utf8Path::new(&format!("crates/store/re_types/definitions/{virtpath}")).canonicalize() + { + path.display().to_string() + } else { + virtpath.to_owned() + } + } } /// Report which holds accumulated errors and warnings. @@ -78,15 +104,17 @@ impl Report { /// This outputs all errors and warnings to stderr and panics if there were any errors. pub fn finalize(&self) { + use colored::Colorize; + let mut errored = false; while let Ok(warn) = self.warnings.try_recv() { - eprintln!("Warning: {warn}"); + eprintln!("{} {}", "Warning: ".yellow().bold(), warn); } while let Ok(err) = self.errors.try_recv() { errored = true; - eprintln!("Error: {err}"); + eprintln!("{} {}", "Error: ".red().bold(), err); } if errored { diff --git a/crates/store/re_types/definitions/rerun/archetypes/graph_edges.fbs b/crates/store/re_types/definitions/rerun/archetypes/graph_edges.fbs index 0d18836848b4..f4e6a7a5988d 100644 --- a/crates/store/re_types/definitions/rerun/archetypes/graph_edges.fbs +++ b/crates/store/re_types/definitions/rerun/archetypes/graph_edges.fbs @@ -27,7 +27,7 @@ table GraphEdges ( /// Specifies if the graph is directed or undirected. /// - /// If no `GraphType` is provided, the graph is assumed to be undirected. + /// If no [components.GraphType] is provided, the graph is assumed to be undirected. graph_type: rerun.components.GraphType ("attr.rerun.component_recommended", nullable, order: 2000); } diff --git a/crates/store/re_types/definitions/rerun/blueprint/archetypes/background.fbs b/crates/store/re_types/definitions/rerun/blueprint/archetypes/background.fbs index adfc5bcfa015..4216f2f8fe6b 100644 --- a/crates/store/re_types/definitions/rerun/blueprint/archetypes/background.fbs +++ b/crates/store/re_types/definitions/rerun/blueprint/archetypes/background.fbs @@ -14,6 +14,7 @@ table Background ( // --- Optional --- - /// Color used for the `SolidColor` background type. + /// Color used for the solid background type. + // TODO(andreas): Can't link to [components.BackgroundKind.SolidColor] since blueprint components aren't part of the doc page yet. color: rerun.components.Color ("attr.rerun.component_optional", nullable, order: 2000); } diff --git a/crates/store/re_types/definitions/rerun/blueprint/archetypes/container_blueprint.fbs b/crates/store/re_types/definitions/rerun/blueprint/archetypes/container_blueprint.fbs index ad5e504b66a4..e2d5afad0bb5 100644 --- a/crates/store/re_types/definitions/rerun/blueprint/archetypes/container_blueprint.fbs +++ b/crates/store/re_types/definitions/rerun/blueprint/archetypes/container_blueprint.fbs @@ -22,16 +22,16 @@ table ContainerBlueprint ( /// The layout shares of each column in the container. /// - /// For `Horizontal` containers, the length of this list should always match the number of contents. + /// For [components.ContainerKind.Horizontal] containers, the length of this list should always match the number of contents. /// - /// Ignored for `Vertical` containers. + /// Ignored for [components.ContainerKind.Vertical] containers. col_shares: [rerun.blueprint.components.ColumnShare] ("attr.rerun.component_optional", nullable, order: 400); /// The layout shares of each row of the container. /// - /// For `Vertical` containers, the length of this list should always match the number of contents. + /// For [components.ContainerKind.Vertical] containers, the length of this list should always match the number of contents. /// - /// Ignored for `Horizontal` containers. + /// Ignored for [components.ContainerKind.Horizontal] containers. row_shares: [rerun.blueprint.components.RowShare] ("attr.rerun.component_optional", nullable, order: 500); /// Which tab is active. @@ -48,6 +48,6 @@ table ContainerBlueprint ( /// /// If unset, the grid layout will be auto. /// - /// Ignored for `Horizontal`/`Vertical` containers. + /// Ignored for [components.ContainerKind.Horizontal]/[components.ContainerKind.Vertical] containers. grid_columns: rerun.blueprint.components.GridColumns ("attr.rerun.component_optional", nullable, order: 800); } diff --git a/crates/store/re_types/definitions/rerun/blueprint/components/visualizer_overrides.fbs b/crates/store/re_types/definitions/rerun/blueprint/components/visualizer_overrides.fbs index 4043917c61f0..fedd2980d452 100644 --- a/crates/store/re_types/definitions/rerun/blueprint/components/visualizer_overrides.fbs +++ b/crates/store/re_types/definitions/rerun/blueprint/components/visualizer_overrides.fbs @@ -21,28 +21,5 @@ table VisualizerOverrides ( "attr.rust.override_crate": "re_types_blueprint" ) { /// Names of the visualizers that should be active. - /// - /// The built-in visualizers are: - /// - `BarChart` - /// - `Arrows2D` - /// - `Arrows3D` - /// - `Asset3D` - /// - `Boxes2D` - /// - `Boxes3D` - /// - `Cameras` - /// - `DepthImage` - /// - `Image` - /// - `Lines2D` - /// - `Lines3D` - /// - `Mesh3D` - /// - `Points2D` - /// - `Points3D` - /// - `Transform3DArrows` - /// - `Tensor` - /// - `TextDocument` - /// - `TextLog` - /// - `SegmentationImage` - /// - `SeriesLine` - /// - `SeriesPoint` visualizers: rerun.blueprint.datatypes.Utf8List (order: 100); } diff --git a/crates/store/re_types/definitions/rerun/components/fill_mode.fbs b/crates/store/re_types/definitions/rerun/components/fill_mode.fbs index 1d9ebcbb3ff2..caf9ec087ac8 100644 --- a/crates/store/re_types/definitions/rerun/components/fill_mode.fbs +++ b/crates/store/re_types/definitions/rerun/components/fill_mode.fbs @@ -18,7 +18,7 @@ enum FillMode: ubyte{ /// /// * An [archetypes.Ellipsoids3D] will draw three axis-aligned ellipses that are cross-sections /// of each ellipsoid, each of which displays two out of three of the sizes of the ellipsoid. - /// * For [archetypes.Boxes3D], it is the edges of the box, identical to `DenseWireframe`. + /// * For [archetypes.Boxes3D], it is the edges of the box, identical to [components.FillMode.DenseWireframe]. MajorWireframe (default), /// Many lines are drawn to represent the surface of the shape in a see-through fashion. @@ -27,7 +27,7 @@ enum FillMode: ubyte{ /// /// * An [archetypes.Ellipsoids3D] will draw a wireframe triangle mesh that approximates each /// ellipsoid. - /// * For [archetypes.Boxes3D], it is the edges of the box, identical to `MajorWireframe`. + /// * For [archetypes.Boxes3D], it is the edges of the box, identical to [components.FillMode.MajorWireframe]. DenseWireframe, /// The surface of the shape is filled in with a solid color. No lines are drawn. diff --git a/crates/store/re_types/definitions/rerun/datatypes/pixel_format.fbs b/crates/store/re_types/definitions/rerun/datatypes/pixel_format.fbs index 91c641c72183..8569f9c4ead9 100644 --- a/crates/store/re_types/definitions/rerun/datatypes/pixel_format.fbs +++ b/crates/store/re_types/definitions/rerun/datatypes/pixel_format.fbs @@ -102,7 +102,7 @@ enum PixelFormat: ubyte { /// followed by a plane with interleaved lines ordered as U0, V0, U1, V1, etc. NV12 = 26 (default), // _something_ has to be the default 🤷‍♀️ - /// `YUY2` (aka `YUYV`, `YUYV16` or `NV21`), is a YUV 4:2:2 chroma downsampled format with 16 bits per pixel and 8 bits per channel. + /// `YUY2` (aka 'YUYV', 'YUYV16' or 'NV21'), is a YUV 4:2:2 chroma downsampled format with 16 bits per pixel and 8 bits per channel. /// /// This uses limited range YUV, i.e. Y is expected to be within [16, 235] and U/V within [16, 240]. /// diff --git a/crates/store/re_types/src/archetypes/graph_edges.rs b/crates/store/re_types/src/archetypes/graph_edges.rs index d8ecb7df7421..f93d9081c749 100644 --- a/crates/store/re_types/src/archetypes/graph_edges.rs +++ b/crates/store/re_types/src/archetypes/graph_edges.rs @@ -30,7 +30,7 @@ pub struct GraphEdges { /// Specifies if the graph is directed or undirected. /// - /// If no `GraphType` is provided, the graph is assumed to be undirected. + /// If no [`components::GraphType`][crate::components::GraphType] is provided, the graph is assumed to be undirected. pub graph_type: Option, } @@ -214,7 +214,7 @@ impl GraphEdges { /// Specifies if the graph is directed or undirected. /// - /// If no `GraphType` is provided, the graph is assumed to be undirected. + /// If no [`components::GraphType`][crate::components::GraphType] is provided, the graph is assumed to be undirected. #[inline] pub fn with_graph_type(mut self, graph_type: impl Into) -> Self { self.graph_type = Some(graph_type.into()); diff --git a/crates/store/re_types/src/blueprint/archetypes/background.rs b/crates/store/re_types/src/blueprint/archetypes/background.rs index c6889b89dfe7..40f46eaf3dd2 100644 --- a/crates/store/re_types/src/blueprint/archetypes/background.rs +++ b/crates/store/re_types/src/blueprint/archetypes/background.rs @@ -24,7 +24,7 @@ pub struct Background { /// The type of the background. pub kind: crate::blueprint::components::BackgroundKind, - /// Color used for the `SolidColor` background type. + /// Color used for the solid background type. pub color: Option, } @@ -206,7 +206,7 @@ impl Background { } } - /// Color used for the `SolidColor` background type. + /// Color used for the solid background type. #[inline] pub fn with_color(mut self, color: impl Into) -> Self { self.color = Some(color.into()); diff --git a/crates/store/re_types/src/components/fill_mode.rs b/crates/store/re_types/src/components/fill_mode.rs index 0873b950a7f1..62626d83d9ed 100644 --- a/crates/store/re_types/src/components/fill_mode.rs +++ b/crates/store/re_types/src/components/fill_mode.rs @@ -29,7 +29,7 @@ pub enum FillMode { /// /// * An [`archetypes::Ellipsoids3D`][crate::archetypes::Ellipsoids3D] will draw three axis-aligned ellipses that are cross-sections /// of each ellipsoid, each of which displays two out of three of the sizes of the ellipsoid. - /// * For [`archetypes::Boxes3D`][crate::archetypes::Boxes3D], it is the edges of the box, identical to `DenseWireframe`. + /// * For [`archetypes::Boxes3D`][crate::archetypes::Boxes3D], it is the edges of the box, identical to [`components::FillMode::DenseWireframe`][crate::components::FillMode::DenseWireframe]. #[default] MajorWireframe = 1, @@ -39,7 +39,7 @@ pub enum FillMode { /// /// * An [`archetypes::Ellipsoids3D`][crate::archetypes::Ellipsoids3D] will draw a wireframe triangle mesh that approximates each /// ellipsoid. - /// * For [`archetypes::Boxes3D`][crate::archetypes::Boxes3D], it is the edges of the box, identical to `MajorWireframe`. + /// * For [`archetypes::Boxes3D`][crate::archetypes::Boxes3D], it is the edges of the box, identical to [`components::FillMode::MajorWireframe`][crate::components::FillMode::MajorWireframe]. DenseWireframe = 2, /// The surface of the shape is filled in with a solid color. No lines are drawn. @@ -155,10 +155,10 @@ impl ::re_types_core::reflection::Enum for FillMode { fn docstring_md(self) -> &'static str { match self { Self::MajorWireframe => { - "Lines are drawn around the parts of the shape which directly correspond to the logged data.\n\nExamples of what this means:\n\n* An [`archetypes::Ellipsoids3D`][crate::archetypes::Ellipsoids3D] will draw three axis-aligned ellipses that are cross-sections\n of each ellipsoid, each of which displays two out of three of the sizes of the ellipsoid.\n* For [`archetypes::Boxes3D`][crate::archetypes::Boxes3D], it is the edges of the box, identical to `DenseWireframe`." + "Lines are drawn around the parts of the shape which directly correspond to the logged data.\n\nExamples of what this means:\n\n* An [`archetypes.Ellipsoids3D`](https://rerun.io/docs/reference/types/archetypes/ellipsoids3d) will draw three axis-aligned ellipses that are cross-sections\n of each ellipsoid, each of which displays two out of three of the sizes of the ellipsoid.\n* For [`archetypes.Boxes3D`](https://rerun.io/docs/reference/types/archetypes/boxes3d), it is the edges of the box, identical to [`components.FillMode#DenseWireframe`](https://rerun.io/docs/reference/types/components/fill_mode)." } Self::DenseWireframe => { - "Many lines are drawn to represent the surface of the shape in a see-through fashion.\n\nExamples of what this means:\n\n* An [`archetypes::Ellipsoids3D`][crate::archetypes::Ellipsoids3D] will draw a wireframe triangle mesh that approximates each\n ellipsoid.\n* For [`archetypes::Boxes3D`][crate::archetypes::Boxes3D], it is the edges of the box, identical to `MajorWireframe`." + "Many lines are drawn to represent the surface of the shape in a see-through fashion.\n\nExamples of what this means:\n\n* An [`archetypes.Ellipsoids3D`](https://rerun.io/docs/reference/types/archetypes/ellipsoids3d) will draw a wireframe triangle mesh that approximates each\n ellipsoid.\n* For [`archetypes.Boxes3D`](https://rerun.io/docs/reference/types/archetypes/boxes3d), it is the edges of the box, identical to [`components.FillMode#MajorWireframe`](https://rerun.io/docs/reference/types/components/fill_mode)." } Self::Solid => { "The surface of the shape is filled in with a solid color. No lines are drawn." diff --git a/crates/store/re_types/src/components/transform_relation.rs b/crates/store/re_types/src/components/transform_relation.rs index 95848e877db6..4fcd383ef19d 100644 --- a/crates/store/re_types/src/components/transform_relation.rs +++ b/crates/store/re_types/src/components/transform_relation.rs @@ -146,10 +146,10 @@ impl ::re_types_core::reflection::Enum for TransformRelation { fn docstring_md(self) -> &'static str { match self { Self::ParentFromChild => { - "The transform describes how to transform into the parent entity's space.\n\nE.g. a translation of (0, 1, 0) with this [`components::TransformRelation`][crate::components::TransformRelation] logged at `parent/child` means\nthat from the point of view of `parent`, `parent/child` is translated 1 unit along `parent`'s Y axis.\nFrom perspective of `parent/child`, the `parent` entity is translated -1 unit along `parent/child`'s Y axis." + "The transform describes how to transform into the parent entity's space.\n\nE.g. a translation of (0, 1, 0) with this [`components.TransformRelation`](https://rerun.io/docs/reference/types/components/transform_relation) logged at `parent/child` means\nthat from the point of view of `parent`, `parent/child` is translated 1 unit along `parent`'s Y axis.\nFrom perspective of `parent/child`, the `parent` entity is translated -1 unit along `parent/child`'s Y axis." } Self::ChildFromParent => { - "The transform describes how to transform into the child entity's space.\n\nE.g. a translation of (0, 1, 0) with this [`components::TransformRelation`][crate::components::TransformRelation] logged at `parent/child` means\nthat from the point of view of `parent`, `parent/child` is translated -1 unit along `parent`'s Y axis.\nFrom perspective of `parent/child`, the `parent` entity is translated 1 unit along `parent/child`'s Y axis." + "The transform describes how to transform into the child entity's space.\n\nE.g. a translation of (0, 1, 0) with this [`components.TransformRelation`](https://rerun.io/docs/reference/types/components/transform_relation) logged at `parent/child` means\nthat from the point of view of `parent`, `parent/child` is translated -1 unit along `parent`'s Y axis.\nFrom perspective of `parent/child`, the `parent` entity is translated 1 unit along `parent/child`'s Y axis." } } } diff --git a/crates/store/re_types/src/datatypes/pixel_format.rs b/crates/store/re_types/src/datatypes/pixel_format.rs index 28d99abf8131..0b7c9aa8301e 100644 --- a/crates/store/re_types/src/datatypes/pixel_format.rs +++ b/crates/store/re_types/src/datatypes/pixel_format.rs @@ -52,7 +52,7 @@ pub enum PixelFormat { #[allow(clippy::upper_case_acronyms)] NV12 = 26, - /// `YUY2` (aka `YUYV`, `YUYV16` or `NV21`), is a YUV 4:2:2 chroma downsampled format with 16 bits per pixel and 8 bits per channel. + /// `YUY2` (aka 'YUYV', 'YUYV16' or 'NV21'), is a YUV 4:2:2 chroma downsampled format with 16 bits per pixel and 8 bits per channel. /// /// This uses limited range YUV, i.e. Y is expected to be within [16, 235] and U/V within [16, 240]. /// @@ -258,10 +258,10 @@ impl ::re_types_core::reflection::Enum for PixelFormat { "`NV12` (aka `Y_UV12`) is a YUV 4:2:0 chroma downsampled form at with 12 bits per pixel and 8 bits per channel.\n\nThis uses limited range YUV, i.e. Y is expected to be within [16, 235] and U/V within [16, 240].\n\nFirst comes entire image in Y in one plane,\nfollowed by a plane with interleaved lines ordered as U0, V0, U1, V1, etc." } Self::YUY2 => { - "`YUY2` (aka `YUYV`, `YUYV16` or `NV21`), is a YUV 4:2:2 chroma downsampled format with 16 bits per pixel and 8 bits per channel.\n\nThis uses limited range YUV, i.e. Y is expected to be within [16, 235] and U/V within [16, 240].\n\nThe order of the channels is Y0, U0, Y1, V0, all in the same plane." + "`YUY2` (aka 'YUYV', 'YUYV16' or 'NV21'), is a YUV 4:2:2 chroma downsampled format with 16 bits per pixel and 8 bits per channel.\n\nThis uses limited range YUV, i.e. Y is expected to be within [16, 235] and U/V within [16, 240].\n\nThe order of the channels is Y0, U0, Y1, V0, all in the same plane." } Self::Y8_FullRange => { - "Monochrome Y plane only, essentially a YUV 4:0:0 planar format.\n\nAlso known as just \"gray\". This is virtually identical to a 8bit luminance/grayscale (see [`datatypes::ColorModel`][crate::datatypes::ColorModel]).\n\nThis uses entire range YUV, i.e. Y is expected to be within [0, 255].\n(as opposed to \"limited range\" YUV as used e.g. in NV12)." + "Monochrome Y plane only, essentially a YUV 4:0:0 planar format.\n\nAlso known as just \"gray\". This is virtually identical to a 8bit luminance/grayscale (see [`datatypes.ColorModel`](https://rerun.io/docs/reference/types/datatypes/color_model)).\n\nThis uses entire range YUV, i.e. Y is expected to be within [0, 255].\n(as opposed to \"limited range\" YUV as used e.g. in NV12)." } Self::Y_U_V24_LimitedRange => { "`Y_U_V24` is a YUV 4:4:4 fully planar YUV format without chroma downsampling, also known as `I444`.\n\nThis uses limited range YUV, i.e. Y is expected to be within [16, 235] and U/V within [16, 240].\n\nFirst comes entire image in Y in one plane, followed by the U and V planes." @@ -270,7 +270,7 @@ impl ::re_types_core::reflection::Enum for PixelFormat { "`Y_U_V24` is a YUV 4:4:4 fully planar YUV format without chroma downsampling, also known as `I444`.\n\nThis uses full range YUV with all components ranging from 0 to 255\n(as opposed to \"limited range\" YUV as used e.g. in NV12).\n\nFirst comes entire image in Y in one plane, followed by the U and V planes." } Self::Y8_LimitedRange => { - "Monochrome Y plane only, essentially a YUV 4:0:0 planar format.\n\nAlso known as just \"gray\".\n\nThis uses limited range YUV, i.e. Y is expected to be within [16, 235].\nIf not for this range limitation/remapping, this is almost identical to 8bit luminace/grayscale (see [`datatypes::ColorModel`][crate::datatypes::ColorModel])." + "Monochrome Y plane only, essentially a YUV 4:0:0 planar format.\n\nAlso known as just \"gray\".\n\nThis uses limited range YUV, i.e. Y is expected to be within [16, 235].\nIf not for this range limitation/remapping, this is almost identical to 8bit luminace/grayscale (see [`datatypes.ColorModel`](https://rerun.io/docs/reference/types/datatypes/color_model))." } Self::Y_U_V12_FullRange => { "`Y_U_V12` is a YUV 4:2:0 fully planar YUV format without chroma downsampling, also known as `I420`.\n\nThis uses full range YUV with all components ranging from 0 to 255\n(as opposed to \"limited range\" YUV as used e.g. in NV12).\n\nFirst comes entire image in Y in one plane, followed by the U and V planes, which each only have half\nthe resolution of the Y plane." diff --git a/crates/store/re_types_blueprint/src/blueprint/archetypes/container_blueprint.rs b/crates/store/re_types_blueprint/src/blueprint/archetypes/container_blueprint.rs index 3138dd3a9254..95e2991da168 100644 --- a/crates/store/re_types_blueprint/src/blueprint/archetypes/container_blueprint.rs +++ b/crates/store/re_types_blueprint/src/blueprint/archetypes/container_blueprint.rs @@ -32,16 +32,16 @@ pub struct ContainerBlueprint { /// The layout shares of each column in the container. /// - /// For `Horizontal` containers, the length of this list should always match the number of contents. + /// For [`components::ContainerKind::Horizontal`][crate::blueprint::components::ContainerKind::Horizontal] containers, the length of this list should always match the number of contents. /// - /// Ignored for `Vertical` containers. + /// Ignored for [`components::ContainerKind::Vertical`][crate::blueprint::components::ContainerKind::Vertical] containers. pub col_shares: Option>, /// The layout shares of each row of the container. /// - /// For `Vertical` containers, the length of this list should always match the number of contents. + /// For [`components::ContainerKind::Vertical`][crate::blueprint::components::ContainerKind::Vertical] containers, the length of this list should always match the number of contents. /// - /// Ignored for `Horizontal` containers. + /// Ignored for [`components::ContainerKind::Horizontal`][crate::blueprint::components::ContainerKind::Horizontal] containers. pub row_shares: Option>, /// Which tab is active. @@ -58,7 +58,7 @@ pub struct ContainerBlueprint { /// /// If unset, the grid layout will be auto. /// - /// Ignored for `Horizontal`/`Vertical` containers. + /// Ignored for [`components::ContainerKind::Horizontal`][crate::blueprint::components::ContainerKind::Horizontal]/[`components::ContainerKind::Vertical`][crate::blueprint::components::ContainerKind::Vertical] containers. pub grid_columns: Option, } @@ -480,9 +480,9 @@ impl ContainerBlueprint { /// The layout shares of each column in the container. /// - /// For `Horizontal` containers, the length of this list should always match the number of contents. + /// For [`components::ContainerKind::Horizontal`][crate::blueprint::components::ContainerKind::Horizontal] containers, the length of this list should always match the number of contents. /// - /// Ignored for `Vertical` containers. + /// Ignored for [`components::ContainerKind::Vertical`][crate::blueprint::components::ContainerKind::Vertical] containers. #[inline] pub fn with_col_shares( mut self, @@ -494,9 +494,9 @@ impl ContainerBlueprint { /// The layout shares of each row of the container. /// - /// For `Vertical` containers, the length of this list should always match the number of contents. + /// For [`components::ContainerKind::Vertical`][crate::blueprint::components::ContainerKind::Vertical] containers, the length of this list should always match the number of contents. /// - /// Ignored for `Horizontal` containers. + /// Ignored for [`components::ContainerKind::Horizontal`][crate::blueprint::components::ContainerKind::Horizontal] containers. #[inline] pub fn with_row_shares( mut self, @@ -534,7 +534,7 @@ impl ContainerBlueprint { /// /// If unset, the grid layout will be auto. /// - /// Ignored for `Horizontal`/`Vertical` containers. + /// Ignored for [`components::ContainerKind::Horizontal`][crate::blueprint::components::ContainerKind::Horizontal]/[`components::ContainerKind::Vertical`][crate::blueprint::components::ContainerKind::Vertical] containers. #[inline] pub fn with_grid_columns( mut self, diff --git a/crates/store/re_types_blueprint/src/blueprint/components/visualizer_overrides.rs b/crates/store/re_types_blueprint/src/blueprint/components/visualizer_overrides.rs index 7bc5a0d63998..99b03d0960a2 100644 --- a/crates/store/re_types_blueprint/src/blueprint/components/visualizer_overrides.rs +++ b/crates/store/re_types_blueprint/src/blueprint/components/visualizer_overrides.rs @@ -32,29 +32,6 @@ use ::re_types_core::{DeserializationError, DeserializationResult}; #[repr(transparent)] pub struct VisualizerOverrides( /// Names of the visualizers that should be active. - /// - /// The built-in visualizers are: - /// - `BarChart` - /// - `Arrows2D` - /// - `Arrows3D` - /// - `Asset3D` - /// - `Boxes2D` - /// - `Boxes3D` - /// - `Cameras` - /// - `DepthImage` - /// - `Image` - /// - `Lines2D` - /// - `Lines3D` - /// - `Mesh3D` - /// - `Points2D` - /// - `Points3D` - /// - `Transform3DArrows` - /// - `Tensor` - /// - `TextDocument` - /// - `TextLog` - /// - `SegmentationImage` - /// - `SeriesLine` - /// - `SeriesPoint` pub crate::blueprint::datatypes::Utf8List, ); diff --git a/crates/viewer/re_viewer/src/reflection/mod.rs b/crates/viewer/re_viewer/src/reflection/mod.rs index ed5806fd9f5b..a32288da7a61 100644 --- a/crates/viewer/re_viewer/src/reflection/mod.rs +++ b/crates/viewer/re_viewer/src/reflection/mod.rs @@ -1358,7 +1358,7 @@ fn generate_archetype_reflection() -> ArchetypeReflectionMap { is_required : true, }, ArchetypeFieldReflection { component_name : "rerun.components.GraphType".into(), display_name : "Graph type", docstring_md : - "Specifies if the graph is directed or undirected.\n\nIf no `GraphType` is provided, the graph is assumed to be undirected.\n\n⚠\u{fe0f} **This type is experimental and may be removed in future versions**", + "Specifies if the graph is directed or undirected.\n\nIf no [`components.GraphType`](https://rerun.io/docs/reference/types/components/graph_type?speculative-link) is provided, the graph is assumed to be undirected.\n\n⚠\u{fe0f} **This type is experimental and may be removed in future versions**", is_required : false, }, ], }, @@ -1871,8 +1871,8 @@ fn generate_archetype_reflection() -> ArchetypeReflectionMap { "Kind", docstring_md : "The type of the background.", is_required : true, }, ArchetypeFieldReflection { component_name : "rerun.components.Color".into(), display_name : "Color", docstring_md - : "Color used for the `SolidColor` background type.", is_required : - false, }, + : "Color used for the solid background type.", is_required : false, + }, ], }, ), @@ -1895,11 +1895,11 @@ fn generate_archetype_reflection() -> ArchetypeReflectionMap { is_required : false, }, ArchetypeFieldReflection { component_name : "rerun.blueprint.components.ColumnShare".into(), display_name : "Col shares", docstring_md : - "The layout shares of each column in the container.\n\nFor `Horizontal` containers, the length of this list should always match the number of contents.\n\nIgnored for `Vertical` containers.", + "The layout shares of each column in the container.\n\nFor [`components.ContainerKind#Horizontal`](https://rerun.io/docs/reference/types/components/container_kind) containers, the length of this list should always match the number of contents.\n\nIgnored for [`components.ContainerKind#Vertical`](https://rerun.io/docs/reference/types/components/container_kind) containers.", is_required : false, }, ArchetypeFieldReflection { component_name : "rerun.blueprint.components.RowShare".into(), display_name : "Row shares", docstring_md : - "The layout shares of each row of the container.\n\nFor `Vertical` containers, the length of this list should always match the number of contents.\n\nIgnored for `Horizontal` containers.", + "The layout shares of each row of the container.\n\nFor [`components.ContainerKind#Vertical`](https://rerun.io/docs/reference/types/components/container_kind) containers, the length of this list should always match the number of contents.\n\nIgnored for [`components.ContainerKind#Horizontal`](https://rerun.io/docs/reference/types/components/container_kind) containers.", is_required : false, }, ArchetypeFieldReflection { component_name : "rerun.blueprint.components.ActiveTab".into(), display_name : "Active tab", docstring_md : @@ -1911,7 +1911,7 @@ fn generate_archetype_reflection() -> ArchetypeReflectionMap { is_required : false, }, ArchetypeFieldReflection { component_name : "rerun.blueprint.components.GridColumns".into(), display_name : "Grid columns", docstring_md : - "How many columns this grid should have.\n\nIf unset, the grid layout will be auto.\n\nIgnored for `Horizontal`/`Vertical` containers.", + "How many columns this grid should have.\n\nIf unset, the grid layout will be auto.\n\nIgnored for [`components.ContainerKind#Horizontal`](https://rerun.io/docs/reference/types/components/container_kind)/[`components.ContainerKind#Vertical`](https://rerun.io/docs/reference/types/components/container_kind) containers.", is_required : false, }, ], }, diff --git a/docs/content/reference/types/components/fill_mode.md b/docs/content/reference/types/components/fill_mode.md index f95ed3ac01a6..a939e3eee30d 100644 --- a/docs/content/reference/types/components/fill_mode.md +++ b/docs/content/reference/types/components/fill_mode.md @@ -13,7 +13,7 @@ Examples of what this means: * An [`archetypes.Ellipsoids3D`](https://rerun.io/docs/reference/types/archetypes/ellipsoids3d) will draw three axis-aligned ellipses that are cross-sections of each ellipsoid, each of which displays two out of three of the sizes of the ellipsoid. -* For [`archetypes.Boxes3D`](https://rerun.io/docs/reference/types/archetypes/boxes3d), it is the edges of the box, identical to `DenseWireframe`. +* For [`archetypes.Boxes3D`](https://rerun.io/docs/reference/types/archetypes/boxes3d), it is the edges of the box, identical to [`components.FillMode#DenseWireframe`](https://rerun.io/docs/reference/types/components/fill_mode). #### `DenseWireframe` = 2 Many lines are drawn to represent the surface of the shape in a see-through fashion. @@ -22,7 +22,7 @@ Examples of what this means: * An [`archetypes.Ellipsoids3D`](https://rerun.io/docs/reference/types/archetypes/ellipsoids3d) will draw a wireframe triangle mesh that approximates each ellipsoid. -* For [`archetypes.Boxes3D`](https://rerun.io/docs/reference/types/archetypes/boxes3d), it is the edges of the box, identical to `MajorWireframe`. +* For [`archetypes.Boxes3D`](https://rerun.io/docs/reference/types/archetypes/boxes3d), it is the edges of the box, identical to [`components.FillMode#MajorWireframe`](https://rerun.io/docs/reference/types/components/fill_mode). #### `Solid` = 3 The surface of the shape is filled in with a solid color. No lines are drawn. diff --git a/docs/content/reference/types/datatypes/pixel_format.md b/docs/content/reference/types/datatypes/pixel_format.md index 187b03583fe0..9b44012f59bd 100644 --- a/docs/content/reference/types/datatypes/pixel_format.md +++ b/docs/content/reference/types/datatypes/pixel_format.md @@ -33,7 +33,7 @@ First comes entire image in Y in one plane, followed by a plane with interleaved lines ordered as U0, V0, U1, V1, etc. #### `YUY2` = 27 -`YUY2` (aka `YUYV`, `YUYV16` or `NV21`), is a YUV 4:2:2 chroma downsampled format with 16 bits per pixel and 8 bits per channel. +`YUY2` (aka 'YUYV', 'YUYV16' or 'NV21'), is a YUV 4:2:2 chroma downsampled format with 16 bits per pixel and 8 bits per channel. This uses limited range YUV, i.e. Y is expected to be within [16, 235] and U/V within [16, 240]. diff --git a/docs/content/reference/types/views/spatial2d_view.md b/docs/content/reference/types/views/spatial2d_view.md index 958e931f5efd..d7a752d0212a 100644 --- a/docs/content/reference/types/views/spatial2d_view.md +++ b/docs/content/reference/types/views/spatial2d_view.md @@ -11,7 +11,7 @@ For viewing spatial 2D data. Configuration for the background of the view. * `kind`: The type of the background. -* `color`: Color used for the `SolidColor` background type. +* `color`: Color used for the solid background type. ### `visual_bounds` The visible parts of the scene, in the coordinate space of the scene. diff --git a/docs/content/reference/types/views/spatial3d_view.md b/docs/content/reference/types/views/spatial3d_view.md index a6efe92e9ac1..47d2adab291b 100644 --- a/docs/content/reference/types/views/spatial3d_view.md +++ b/docs/content/reference/types/views/spatial3d_view.md @@ -11,7 +11,7 @@ For viewing spatial 3D data. Configuration for the background of the view. * `kind`: The type of the background. -* `color`: Color used for the `SolidColor` background type. +* `color`: Color used for the solid background type. ### `line_grid` Configuration for the 3D line grid. diff --git a/rerun_cpp/src/rerun/archetypes/graph_edges.hpp b/rerun_cpp/src/rerun/archetypes/graph_edges.hpp index 65863e21c154..4e60d8e23d82 100644 --- a/rerun_cpp/src/rerun/archetypes/graph_edges.hpp +++ b/rerun_cpp/src/rerun/archetypes/graph_edges.hpp @@ -28,7 +28,7 @@ namespace rerun::archetypes { /// Specifies if the graph is directed or undirected. /// - /// If no `GraphType` is provided, the graph is assumed to be undirected. + /// If no `components::GraphType` is provided, the graph is assumed to be undirected. std::optional graph_type; public: @@ -47,7 +47,7 @@ namespace rerun::archetypes { /// Specifies if the graph is directed or undirected. /// - /// If no `GraphType` is provided, the graph is assumed to be undirected. + /// If no `components::GraphType` is provided, the graph is assumed to be undirected. GraphEdges with_graph_type(rerun::components::GraphType _graph_type) && { graph_type = std::move(_graph_type); // See: https://github.com/rerun-io/rerun/issues/4027 diff --git a/rerun_cpp/src/rerun/blueprint/archetypes/background.hpp b/rerun_cpp/src/rerun/blueprint/archetypes/background.hpp index 044b3b3cff1e..4f66607a5cb4 100644 --- a/rerun_cpp/src/rerun/blueprint/archetypes/background.hpp +++ b/rerun_cpp/src/rerun/blueprint/archetypes/background.hpp @@ -22,7 +22,7 @@ namespace rerun::blueprint::archetypes { /// The type of the background. rerun::blueprint::components::BackgroundKind kind; - /// Color used for the `SolidColor` background type. + /// Color used for the solid background type. std::optional color; public: @@ -39,7 +39,7 @@ namespace rerun::blueprint::archetypes { explicit Background(rerun::blueprint::components::BackgroundKind _kind) : kind(std::move(_kind)) {} - /// Color used for the `SolidColor` background type. + /// Color used for the solid background type. Background with_color(rerun::components::Color _color) && { color = std::move(_color); // See: https://github.com/rerun-io/rerun/issues/4027 diff --git a/rerun_cpp/src/rerun/blueprint/archetypes/container_blueprint.hpp b/rerun_cpp/src/rerun/blueprint/archetypes/container_blueprint.hpp index 9e7d8ae594ce..19377b7ab6f7 100644 --- a/rerun_cpp/src/rerun/blueprint/archetypes/container_blueprint.hpp +++ b/rerun_cpp/src/rerun/blueprint/archetypes/container_blueprint.hpp @@ -36,16 +36,16 @@ namespace rerun::blueprint::archetypes { /// The layout shares of each column in the container. /// - /// For `Horizontal` containers, the length of this list should always match the number of contents. + /// For `components::ContainerKind::Horizontal` containers, the length of this list should always match the number of contents. /// - /// Ignored for `Vertical` containers. + /// Ignored for `components::ContainerKind::Vertical` containers. std::optional> col_shares; /// The layout shares of each row of the container. /// - /// For `Vertical` containers, the length of this list should always match the number of contents. + /// For `components::ContainerKind::Vertical` containers, the length of this list should always match the number of contents. /// - /// Ignored for `Horizontal` containers. + /// Ignored for `components::ContainerKind::Horizontal` containers. std::optional> row_shares; /// Which tab is active. @@ -62,7 +62,7 @@ namespace rerun::blueprint::archetypes { /// /// If unset, the grid layout will be auto. /// - /// Ignored for `Horizontal`/`Vertical` containers. + /// Ignored for `components::ContainerKind::Horizontal`/`components::ContainerKind::Vertical` containers. std::optional grid_columns; public: @@ -97,9 +97,9 @@ namespace rerun::blueprint::archetypes { /// The layout shares of each column in the container. /// - /// For `Horizontal` containers, the length of this list should always match the number of contents. + /// For `components::ContainerKind::Horizontal` containers, the length of this list should always match the number of contents. /// - /// Ignored for `Vertical` containers. + /// Ignored for `components::ContainerKind::Vertical` containers. ContainerBlueprint with_col_shares( Collection _col_shares ) && { @@ -110,9 +110,9 @@ namespace rerun::blueprint::archetypes { /// The layout shares of each row of the container. /// - /// For `Vertical` containers, the length of this list should always match the number of contents. + /// For `components::ContainerKind::Vertical` containers, the length of this list should always match the number of contents. /// - /// Ignored for `Horizontal` containers. + /// Ignored for `components::ContainerKind::Horizontal` containers. ContainerBlueprint with_row_shares( Collection _row_shares ) && { @@ -143,7 +143,7 @@ namespace rerun::blueprint::archetypes { /// /// If unset, the grid layout will be auto. /// - /// Ignored for `Horizontal`/`Vertical` containers. + /// Ignored for `components::ContainerKind::Horizontal`/`components::ContainerKind::Vertical` containers. ContainerBlueprint with_grid_columns(rerun::blueprint::components::GridColumns _grid_columns ) && { grid_columns = std::move(_grid_columns); diff --git a/rerun_cpp/src/rerun/blueprint/components/visualizer_overrides.hpp b/rerun_cpp/src/rerun/blueprint/components/visualizer_overrides.hpp index 4445c860f934..62b251c8253b 100644 --- a/rerun_cpp/src/rerun/blueprint/components/visualizer_overrides.hpp +++ b/rerun_cpp/src/rerun/blueprint/components/visualizer_overrides.hpp @@ -26,29 +26,6 @@ namespace rerun::blueprint::components { /// in a regular entity. struct VisualizerOverrides { /// Names of the visualizers that should be active. - /// - /// The built-in visualizers are: - /// - `BarChart` - /// - `Arrows2D` - /// - `Arrows3D` - /// - `Asset3D` - /// - `Boxes2D` - /// - `Boxes3D` - /// - `Cameras` - /// - `DepthImage` - /// - `Image` - /// - `Lines2D` - /// - `Lines3D` - /// - `Mesh3D` - /// - `Points2D` - /// - `Points3D` - /// - `Transform3DArrows` - /// - `Tensor` - /// - `TextDocument` - /// - `TextLog` - /// - `SegmentationImage` - /// - `SeriesLine` - /// - `SeriesPoint` rerun::blueprint::datatypes::Utf8List visualizers; public: diff --git a/rerun_cpp/src/rerun/components/fill_mode.hpp b/rerun_cpp/src/rerun/components/fill_mode.hpp index 69ddbcc8844d..34ade53cd3da 100644 --- a/rerun_cpp/src/rerun/components/fill_mode.hpp +++ b/rerun_cpp/src/rerun/components/fill_mode.hpp @@ -30,7 +30,7 @@ namespace rerun::components { /// /// * An `archetypes::Ellipsoids3D` will draw three axis-aligned ellipses that are cross-sections /// of each ellipsoid, each of which displays two out of three of the sizes of the ellipsoid. - /// * For `archetypes::Boxes3D`, it is the edges of the box, identical to `DenseWireframe`. + /// * For `archetypes::Boxes3D`, it is the edges of the box, identical to `components::FillMode::DenseWireframe`. MajorWireframe = 1, /// Many lines are drawn to represent the surface of the shape in a see-through fashion. @@ -39,7 +39,7 @@ namespace rerun::components { /// /// * An `archetypes::Ellipsoids3D` will draw a wireframe triangle mesh that approximates each /// ellipsoid. - /// * For `archetypes::Boxes3D`, it is the edges of the box, identical to `MajorWireframe`. + /// * For `archetypes::Boxes3D`, it is the edges of the box, identical to `components::FillMode::MajorWireframe`. DenseWireframe = 2, /// The surface of the shape is filled in with a solid color. No lines are drawn. diff --git a/rerun_cpp/src/rerun/datatypes/pixel_format.hpp b/rerun_cpp/src/rerun/datatypes/pixel_format.hpp index d4123bdebe2c..8130cec4f77b 100644 --- a/rerun_cpp/src/rerun/datatypes/pixel_format.hpp +++ b/rerun_cpp/src/rerun/datatypes/pixel_format.hpp @@ -50,7 +50,7 @@ namespace rerun::datatypes { /// followed by a plane with interleaved lines ordered as U0, V0, U1, V1, etc. NV12 = 26, - /// `YUY2` (aka `YUYV`, `YUYV16` or `NV21`), is a YUV 4:2:2 chroma downsampled format with 16 bits per pixel and 8 bits per channel. + /// `YUY2` (aka 'YUYV', 'YUYV16' or 'NV21'), is a YUV 4:2:2 chroma downsampled format with 16 bits per pixel and 8 bits per channel. /// /// This uses limited range YUV, i.e. Y is expected to be within [16, 235] and U/V within [16, 240]. /// diff --git a/rerun_py/rerun_sdk/rerun/archetypes/graph_edges.py b/rerun_py/rerun_sdk/rerun/archetypes/graph_edges.py index efd87dbb8f19..4fa4c6017d9b 100644 --- a/rerun_py/rerun_sdk/rerun/archetypes/graph_edges.py +++ b/rerun_py/rerun_sdk/rerun/archetypes/graph_edges.py @@ -39,7 +39,7 @@ def __init__(self: Any, edges: datatypes.Utf8PairArrayLike, *, graph_type: compo graph_type: Specifies if the graph is directed or undirected. - If no `GraphType` is provided, the graph is assumed to be undirected. + If no [`components.GraphType`][rerun.components.GraphType] is provided, the graph is assumed to be undirected. """ @@ -78,7 +78,7 @@ def _clear(cls) -> GraphEdges: ) # Specifies if the graph is directed or undirected. # - # If no `GraphType` is provided, the graph is assumed to be undirected. + # If no [`components.GraphType`][rerun.components.GraphType] is provided, the graph is assumed to be undirected. # # (Docstring intentionally commented out to hide this field from the docs) diff --git a/rerun_py/rerun_sdk/rerun/blueprint/archetypes/background.py b/rerun_py/rerun_sdk/rerun/blueprint/archetypes/background.py index 96d90e5ae39e..cbe9178d7911 100644 --- a/rerun_py/rerun_sdk/rerun/blueprint/archetypes/background.py +++ b/rerun_py/rerun_sdk/rerun/blueprint/archetypes/background.py @@ -50,7 +50,7 @@ def _clear(cls) -> Background: default=None, converter=components.ColorBatch._optional, # type: ignore[misc] ) - # Color used for the `SolidColor` background type. + # Color used for the solid background type. # # (Docstring intentionally commented out to hide this field from the docs) diff --git a/rerun_py/rerun_sdk/rerun/blueprint/archetypes/container_blueprint.py b/rerun_py/rerun_sdk/rerun/blueprint/archetypes/container_blueprint.py index dc23b161a5a7..967fab8cb43c 100644 --- a/rerun_py/rerun_sdk/rerun/blueprint/archetypes/container_blueprint.py +++ b/rerun_py/rerun_sdk/rerun/blueprint/archetypes/container_blueprint.py @@ -49,15 +49,15 @@ def __init__( col_shares: The layout shares of each column in the container. - For `Horizontal` containers, the length of this list should always match the number of contents. + For [`components.ContainerKind.Horizontal`][rerun.blueprint.components.ContainerKind.Horizontal] containers, the length of this list should always match the number of contents. - Ignored for `Vertical` containers. + Ignored for [`components.ContainerKind.Vertical`][rerun.blueprint.components.ContainerKind.Vertical] containers. row_shares: The layout shares of each row of the container. - For `Vertical` containers, the length of this list should always match the number of contents. + For [`components.ContainerKind.Vertical`][rerun.blueprint.components.ContainerKind.Vertical] containers, the length of this list should always match the number of contents. - Ignored for `Horizontal` containers. + Ignored for [`components.ContainerKind.Horizontal`][rerun.blueprint.components.ContainerKind.Horizontal] containers. active_tab: Which tab is active. @@ -71,7 +71,7 @@ def __init__( If unset, the grid layout will be auto. - Ignored for `Horizontal`/`Vertical` containers. + Ignored for [`components.ContainerKind.Horizontal`][rerun.blueprint.components.ContainerKind.Horizontal]/[`components.ContainerKind.Vertical`][rerun.blueprint.components.ContainerKind.Vertical] containers. """ @@ -143,9 +143,9 @@ def _clear(cls) -> ContainerBlueprint: ) # The layout shares of each column in the container. # - # For `Horizontal` containers, the length of this list should always match the number of contents. + # For [`components.ContainerKind.Horizontal`][rerun.blueprint.components.ContainerKind.Horizontal] containers, the length of this list should always match the number of contents. # - # Ignored for `Vertical` containers. + # Ignored for [`components.ContainerKind.Vertical`][rerun.blueprint.components.ContainerKind.Vertical] containers. # # (Docstring intentionally commented out to hide this field from the docs) @@ -156,9 +156,9 @@ def _clear(cls) -> ContainerBlueprint: ) # The layout shares of each row of the container. # - # For `Vertical` containers, the length of this list should always match the number of contents. + # For [`components.ContainerKind.Vertical`][rerun.blueprint.components.ContainerKind.Vertical] containers, the length of this list should always match the number of contents. # - # Ignored for `Horizontal` containers. + # Ignored for [`components.ContainerKind.Horizontal`][rerun.blueprint.components.ContainerKind.Horizontal] containers. # # (Docstring intentionally commented out to hide this field from the docs) @@ -193,7 +193,7 @@ def _clear(cls) -> ContainerBlueprint: # # If unset, the grid layout will be auto. # - # Ignored for `Horizontal`/`Vertical` containers. + # Ignored for [`components.ContainerKind.Horizontal`][rerun.blueprint.components.ContainerKind.Horizontal]/[`components.ContainerKind.Vertical`][rerun.blueprint.components.ContainerKind.Vertical] containers. # # (Docstring intentionally commented out to hide this field from the docs) diff --git a/rerun_py/rerun_sdk/rerun/components/fill_mode.py b/rerun_py/rerun_sdk/rerun/components/fill_mode.py index 02ede1978d32..8b4d664a6ec4 100644 --- a/rerun_py/rerun_sdk/rerun/components/fill_mode.py +++ b/rerun_py/rerun_sdk/rerun/components/fill_mode.py @@ -32,7 +32,7 @@ class FillMode(Enum): * An [`archetypes.Ellipsoids3D`][rerun.archetypes.Ellipsoids3D] will draw three axis-aligned ellipses that are cross-sections of each ellipsoid, each of which displays two out of three of the sizes of the ellipsoid. - * For [`archetypes.Boxes3D`][rerun.archetypes.Boxes3D], it is the edges of the box, identical to `DenseWireframe`. + * For [`archetypes.Boxes3D`][rerun.archetypes.Boxes3D], it is the edges of the box, identical to [`components.FillMode.DenseWireframe`][rerun.components.FillMode.DenseWireframe]. """ DenseWireframe = 2 @@ -43,7 +43,7 @@ class FillMode(Enum): * An [`archetypes.Ellipsoids3D`][rerun.archetypes.Ellipsoids3D] will draw a wireframe triangle mesh that approximates each ellipsoid. - * For [`archetypes.Boxes3D`][rerun.archetypes.Boxes3D], it is the edges of the box, identical to `MajorWireframe`. + * For [`archetypes.Boxes3D`][rerun.archetypes.Boxes3D], it is the edges of the box, identical to [`components.FillMode.MajorWireframe`][rerun.components.FillMode.MajorWireframe]. """ Solid = 3 diff --git a/rerun_py/rerun_sdk/rerun/datatypes/pixel_format.py b/rerun_py/rerun_sdk/rerun/datatypes/pixel_format.py index e7505a40720c..5728c69895c0 100644 --- a/rerun_py/rerun_sdk/rerun/datatypes/pixel_format.py +++ b/rerun_py/rerun_sdk/rerun/datatypes/pixel_format.py @@ -56,7 +56,7 @@ class PixelFormat(Enum): YUY2 = 27 """ - `YUY2` (aka `YUYV`, `YUYV16` or `NV21`), is a YUV 4:2:2 chroma downsampled format with 16 bits per pixel and 8 bits per channel. + `YUY2` (aka 'YUYV', 'YUYV16' or 'NV21'), is a YUV 4:2:2 chroma downsampled format with 16 bits per pixel and 8 bits per channel. This uses limited range YUV, i.e. Y is expected to be within [16, 235] and U/V within [16, 240].