C++ Doxygen documentation & many doc improvements (#4191)

### What

**Try it yourself:**
https://wumpf.github.io/rerun-cpp-doc-test/
(yes I sacrificed a repo for this ;))
Or to get a perfect up to date version now and in the future just run
`pixi run cpp-docs`, the docs appear then in
`rerun_cpp/docs/html/index.html`

* fixes _almost_ #3974
* Missing are:
   * process to upload it to landing and link it up in our docs
   * more thorough pass to improve docs overall
* lots of stuff is undocumented. We should consider making this an error
in doxygen (I disabled it for the time being!)

After some back and forth I landed with a pure doxygen documentation
using the impressively good
https://jothepro.github.io/doxygen-awesome-css/ css.
To avoid submoduling and make customization easy, the theme is embedded
in our repo.

Otherwise tons of improvements on our doc strings. Started a guide on
how to write docs similar to what we have for python.

Quite happy with it as-is already. Some of the doc improvements to be
done are also related to smaller code refactors I want to do :)

Review tip: The first commit contains the default doxygen file, if you
want to know what I changed about it just exclude it.

Bunch of screenshots for the lazy:

![image](https://github.com/rerun-io/rerun/assets/1220815/e603c1a4-07a9-4695-b9c7-d2980bb314fb)

![image](https://github.com/rerun-io/rerun/assets/1220815/ffe825ca-5d4a-499d-a6ae-e4dc50ac761f)

![image](https://github.com/rerun-io/rerun/assets/1220815/783846b1-e7cb-4a9a-8491-c5ab98499bd2)


### Checklist
* [x] I have read and agree to [Contributor
Guide](https://github.com/rerun-io/rerun/blob/main/CONTRIBUTING.md) and
the [Code of
Conduct](https://github.com/rerun-io/rerun/blob/main/CODE_OF_CONDUCT.md)
* [x] I've included a screenshot or gif (if applicable)
* [x] I have tested [demo.rerun.io](https://demo.rerun.io/pr/4191) (if
applicable)
* [x] The PR title and labels are set such as to maximize their
usefulness for the next release's CHANGELOG

- [PR Build Summary](https://build.rerun.io/pr/4191)
- [Docs
preview](https://rerun.io/preview/aa7c49ed49fe8fee18be914ccf604662143c7833/docs)
<!--DOCS-PREVIEW-->
- [Examples
preview](https://rerun.io/preview/aa7c49ed49fe8fee18be914ccf604662143c7833/examples)
<!--EXAMPLES-PREVIEW-->
- [Recent benchmark results](https://ref.rerun.io/dev/bench/)
- [Wasm size tracking](https://ref.rerun.io/dev/sizes/)

.github/workflows/cpp_matrix_full.json

@@ -4,7 +4,8 @@
             "name": "Linux x64, C++17",
             "runs_on": "ubuntu-latest-16-cores",
             "cache_key": "build-linux",
-            "extra_env_vars": "RERUN_USE_ASAN=1 RERUN_SET_CXX_VERSION=17"
+            "extra_env_vars": "RERUN_USE_ASAN=1 RERUN_SET_CXX_VERSION=17",
+            "additional_commands": "pixi run cpp-docs"
         },
         {
             "name": "Linux x64, C++20",

.github/workflows/cpp_matrix_partial.json

@@ -4,7 +4,8 @@
             "name": "Linux x64",
             "runs_on": "ubuntu-latest-16-cores",
             "cache_key": "build-linux",
-            "extra_env_vars": ""
+            "extra_env_vars": "",
+            "additional_commands": "pixi run cpp-docs"
         }
     ]
 }

.github/workflows/reusable_checks_cpp.yml

@@ -90,3 +90,4 @@ jobs:
           pixi run cpp-clean
           ${{ matrix.extra_env_vars }} RERUN_WERROR=ON pixi run cpp-build-all
           ${{ matrix.extra_env_vars }} RERUN_WERROR=ON pixi run cpp-test
+          ${{ matrix.additional_commands }}

.gitignore

@@ -17,6 +17,7 @@ crates/re_types_builder/source_hash.txt
 **/cmake_install.cmake
 _deps
 **/.cache/
+**/rerun_cpp/docs/html
 
 # Rust compile target directory:
 **/target

crates/re_types_builder/src/codegen/common.rs

@@ -225,6 +225,16 @@ impl RerunImageUrl<'_> {
 
         stack
     }
+
+    pub fn markdown_tag(&self) -> String {
+        let RerunImageUrl {
+            name,
+            hash,
+            max_width: _,
+            extension,
+        } = *self;
+        format!("![image](https://static.rerun.io/{name}/{hash}/full.{extension})")
+    }
 }
 
 pub struct Example<'a> {

crates/re_types_builder/src/codegen/cpp/forward_decl.rs

@@ -3,7 +3,7 @@ use std::collections::{BTreeMap, BTreeSet};
 use proc_macro2::{Ident, TokenStream};
 use quote::{format_ident, quote};
 
-use super::NEWLINE_TOKEN;
+use super::{quote_hide_from_docs, NEWLINE_TOKEN};
 
 /// A C++ forward declaration.
 #[derive(Debug, Clone)]
@@ -64,7 +64,10 @@ impl quote::ToTokens for ForwardDecl {
                 quote! { class #name; }
             }
             ForwardDecl::TemplateClass(name) => {
+                // Doxygen likes including template declarations in the docs.
+                let hide_from_docs = quote_hide_from_docs();
                 quote! {
+                    #hide_from_docs
                     template<typename T> class #name;
                     #NEWLINE_TOKEN
                     #NEWLINE_TOKEN

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

@@ -46,6 +46,14 @@ fn quote_doc_comment(text: &str) -> TokenStream {
     quote! { #DOC_COMMENT_PREFIX_TOKEN #text #DOC_COMMENT_SUFFIX_TOKEN }
 }
 
+fn quote_hide_from_docs() -> TokenStream {
+    let comment = quote_doc_comment("\\private");
+    quote! {
+        #NEWLINE_TOKEN
+        #comment
+    }
+}
+
 fn string_from_token_stream(token_stream: &TokenStream, source_path: Option<&Utf8Path>) -> String {
     let mut code = String::new();
     code.push_str(&format!("// {}\n", autogen_warning!()));
@@ -479,6 +487,7 @@ impl QuotedObject {
         };
 
         let indicator_comment = quote_doc_comment("Indicator component, used to identify the archetype when converting to a list of components.");
+        let doc_hide_comment = quote_hide_from_docs();
 
         let hpp = quote! {
             #hpp_includes
@@ -505,10 +514,12 @@ impl QuotedObject {
                 #NEWLINE_TOKEN
                 #NEWLINE_TOKEN
 
-                // Instead of including as_components.hpp, simply re-declare the template since it's trivial.
+                // Instead of including as_components.hpp, simply re-declare the template since it's trivial
+                #doc_hide_comment
                 template<typename T>
                 struct AsComponents;
 
+                #doc_hide_comment
                 template<>
                 struct AsComponents<archetypes::#type_ident> {
                     #serialize_hpp
@@ -983,6 +994,7 @@ impl QuotedObject {
         };
 
         let swap_comment = quote_comment("This bitwise swap would fail for self-referential types, but we don't have any of those.");
+        let hide_from_docs_comment = quote_hide_from_docs();
 
         let methods_hpp = methods.iter().map(|m| m.to_hpp_tokens());
         let hpp = quote! {
@@ -993,10 +1005,12 @@ impl QuotedObject {
             namespace rerun {
                 namespace #namespace_ident {
                     namespace detail {
+                        #hide_from_docs_comment
                         enum class #tag_typename : uint8_t {
                             #(#tag_fields)*
                         };
 
+                        #hide_from_docs_comment
                         union #data_typename {
                             #(#enum_data_declarations;)*
 
@@ -2076,10 +2090,7 @@ fn lines_from_docs(docs: &Docs) -> Vec<String> {
         let mut examples = examples.into_iter().peekable();
         while let Some(example) = examples.next() {
             let ExampleInfo {
-                name,
-                title,
-                image: _, // TODO(andreas): Include images in doc
-                ..
+                name, title, image, ..
             } = &example.base;
 
             for line in &example.lines {
@@ -2091,7 +2102,18 @@ fn lines_from_docs(docs: &Docs) -> Vec<String> {
             } else {
                 lines.push(format!("### `{name}`:"));
             }
-            lines.push("```cpp,ignore".into());
+
+            if let Some(image) = image {
+                match image {
+                    super::common::ImageUrl::Rerun(image) => lines.push(image.markdown_tag()),
+                    super::common::ImageUrl::Other(url) => {
+                        lines.push(format!("![example image]({url})"));
+                    }
+                }
+                lines.push(String::new());
+            }
+
+            lines.push("```cpp".into());
             lines.extend(example.lines.iter().cloned());
             lines.push("```".into());
             if examples.peek().is_some() {

docs/cspell.json

@@ -60,6 +60,7 @@
     "colormaps",
     "colorrgba",
     "comms",
+    "cond",
     "constexpr",
     "consts",
     "controlnet",
@@ -86,6 +87,7 @@
     "dont",
     "downscaled",
     "downscaling",
+    "Doxygen",
     "drawables",
     "DRERUN",
     "dtype",
@@ -97,6 +99,7 @@
     "ehttp",
     "Eigen",
     "emilk",
+    "endcond",
     "enumflags",
     "everytime",
     "ewebsock",

pixi.toml

@@ -76,6 +76,7 @@ cpp-log-benchmark = { cmd = "export RERUN_STRICT=1 && ./build/tests/cpp/log_benc
   "cpp-build-log-benchmark",
 ] }
 cpp-build-and-test-all = { depends_on = ["cpp-build-all", "cpp-test"] }
+cpp-docs = { cmd = "doxygen rerun_cpp/docs/Doxyfile" }
 
 [target.win-64.tasks]
 cpp-prepare-msvc = "cmake -G 'Visual Studio 17 2022' -B build-msvc -S ."
@@ -103,6 +104,9 @@ typing_extensions = ">4.5"
 typos = ">=1.16.20"
 wheel = ">=0.38,<0.39"
 ninja = "1.11.1"
+# Make sure to use a version that is compatible with
+# the theme we're using, see https://github.com/jothepro/doxygen-awesome-css/blob/v2.2.1/README.md
+doxygen = "1.9.7.*"
 
 [target.linux-64.dependencies]
 patchelf = ">=0.17"

rerun_cpp/README.md

@@ -4,6 +4,21 @@ The Rerun C++ SDK allows logging data to Rerun directly from C++.
 
 Read the [getting started guide](https://www.rerun.io/docs/getting-started/cpp) for information on how to use the Rerun C++ SDK.
 
+## Building Blocks
+
+The most important type in the SDK is the `rerun::RecordingStream`.
+It allows you to connect to the Rerun Viewer and send data.
+
+The built-in types are distributed to the respective namespaces:
+* `rerun::archetypes`
+* `rerun::components`
+* `rerun::datatypes`
+
+If you include `rerun.hpp`, all archetypes and selected components become part of the `rerun` namespace.
+
+Check the [general doc page on types](https://www.rerun.io/docs/reference/types) to learn more.
+
+
 ## Build & Distribution
 
 ### Overview
@@ -25,7 +40,7 @@ From a build system perspective, the SDK consists of three dependencies:
   * See [Install arrow-cpp](https://www.rerun.io/docs/howto/arrow-cpp-install) for how to install this library
 
 
-### SDK bundle (`rerun_cpp_sdk.zip`)
+### SDK bundle `rerun_cpp_sdk.zip`
 
 For convenience, Rerun provides a C++ SDK bundle with every release.
 (this includes our regular [Development Builds](https://github.com/rerun-io/rerun/releases/tag/prerelease)!)