Support \example in codegen

[jprochazk]

What

• Adds support for \example tag which replaces existing dance around examples included via \py, \rs, and \cpp
• Fixes whitespace handling of examples
  • Examples were not being properly indented:
    

    rerun/rerun_cpp/src/rerun/archetypes/points3d.hpp

    Lines 29 to 42 in b2f7f19

    	///```
    	///// Log some very simple points.
    	///
    	/// #include <rerun.hpp>
    	///
    	/// namespace rr = rerun;
    	///
    	/// int main() {
    	/// auto rec = rr::RecordingStream("rerun_example_points3d_simple");
    	/// rec.connect("127.0.0.1:9876").throw_on_failure();
    	///
    	/// rec.log("points", rr::Points3D({{0.0f, 0.0f, 0.0f}, {1.0f, 1.0f, 1.0f}}));
    	/// }
    	///```

  • This fixes that by delegating the whitespace handling to the specific language implementation.
    • Python removes leading whitespace for doc comments (but not examples, as those are already unindented)
    • Rust and C++ adds the leading whitespace as necessary
      • Doc content is left as is for the most part, with some special handling around converting #[doc="..."] tokens to /// ...
      • Examples are indented with 1 space
• Added Context, which means we can now collect errors instead of failing immediately on the first one.
  • For example, removing a few of the .rs code examples:

    couldn't open code example "/home/jp/rerun-io/rerun/docs/code-examples/clear_simple.rs"
    couldn't open code example "/home/jp/rerun-io/rerun/docs/code-examples/image_simple.rs"
    couldn't open code example "/home/jp/rerun-io/rerun/docs/code-examples/box2d_simple.rs"
    couldn't open code example "/home/jp/rerun-io/rerun/docs/code-examples/depth_image_simple.rs"
    

Checklist

• I have read and agree to Contributor Guide and the Code of Conduct
• I've included a screenshot or gif (if applicable)
• I have tested demo.rerun.io (if applicable)

• PR Build Summary
• Docs preview
• Examples preview
• Recent benchmark results
• Wasm size tracking

[emilk]

It's a shame to loose the example titles, but otherwise LGTM.

Nice to get that whitespace correct!

[emilk]

In wonder if we should really require that all languages has all examples. Some examples only makes sense in some languages, e.g. an example of how to convert a python PIL image to a Rerun image, or similar.

I think it makes sense to require that each language has at least one example per archetype though.

[jprochazk]

I was going to add stricter checks (check that each archetype has an \example), but decided to hold off for now. I think this would be good to discuss during standup

[emilk]

Super!