Improve docs for TextDocument example (#4008)

### What
* Closes #3904
* Closes #3905

This enabled the API-docs for the `TextDocument` example. To make sure
it renders correctly I needed to:

* Remove the ```-code block (for proper embedding in the website inside
of a ``` markdown block)
* Replace `""""` with `''''` in the python example, so it can be
embedded in a `"""`-docstring in the Python API docs


#### Python API docs:

![image](https://github.com/rerun-io/rerun/assets/1148717/e9d2b814-1aa6-4018-bc76-c53aa6dbc829)

#### Rust API docs:

![image](https://github.com/rerun-io/rerun/assets/1148717/9b013213-41c1-4692-bfb9-e29b0c592c9f)


### 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/4008) (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/4008)
- [Docs
preview](https://rerun.io/preview/a8947d56d39d866f14791d6bb57fafad32323c5b/docs)
<!--DOCS-PREVIEW-->
- [Examples
preview](https://rerun.io/preview/a8947d56d39d866f14791d6bb57fafad32323c5b/examples)
<!--EXAMPLES-PREVIEW-->
- [Recent benchmark results](https://ref.rerun.io/dev/bench/)
- [Wasm size tracking](https://ref.rerun.io/dev/sizes/)

crates/re_types/definitions/rerun/archetypes/text_document.fbs

@@ -11,7 +11,7 @@ namespace rerun.archetypes;
 ///
 /// Supports raw text and markdown.
 ///
-/// \example text_document !api title="Markdown text document" image="https://static.rerun.io/textdocument/babda19558ee32ed8d730495b595aee7a5e2c174/1200w.png"
+/// \example text_document title="Markdown text document" image="https://static.rerun.io/textdocument/babda19558ee32ed8d730495b595aee7a5e2c174/1200w.png"
 table TextDocument (
   "attr.rust.derive": "PartialEq, Eq"
 ) {

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

@@ -2068,6 +2068,10 @@ fn lines_from_docs(docs: &Docs) -> Vec<String> {
                 ..
             } = &example.base;
 
+            for line in &example.lines {
+                assert!(!line.contains("```"), "Example {name:?} contains ``` in it, so we can't embed it in the C++ API docs.");
+            }
+
             if let Some(title) = title {
                 lines.push(format!("### {title}"));
             } else {

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

@@ -192,7 +192,11 @@ fn object_page(reporter: &Reporter, object: &Object, object_map: &ObjectMap) ->
             putln!(page);
             write_used_by(&mut page, reporter, object, object_map);
         }
-        ObjectKind::Blueprint | ObjectKind::Archetype => {}
+        ObjectKind::Blueprint | ObjectKind::Archetype => {
+            if examples.is_empty() {
+                reporter.warn(&object.virtpath, &object.fqname, "No examples");
+            }
+        }
     }
 
     page
@@ -259,7 +263,9 @@ fn write_used_by(o: &mut String, reporter: &Reporter, object: &Object, object_ma
         // reference other tables, but they are unwrapped in the codegen.
         // So for instance: `union Angle` uses `rerun.datatypes.Float32` in
         // `angle.fbs`, but in the generated code that datatype is unused.
-        reporter.warn(&object.virtpath, &object.fqname, "Unused object");
+        if false {
+            reporter.warn(&object.virtpath, &object.fqname, "Unused object");
+        }
     } else {
         putln!(o, "## Used by");
         putln!(o);

crates/re_types_builder/src/codegen/python.rs

@@ -875,13 +875,41 @@ fn quote_examples(examples: Vec<Example<'_>>, lines: &mut Vec<String>) {
             name, title, image, ..
         } = &example.base;
 
+        let mut example_lines = example.lines.clone();
+
+        if let Some(first_line) = example_lines.first() {
+            if first_line.starts_with("\"\"\"")
+                && first_line.ends_with("\"\"\"")
+                && first_line.len() > 6
+            {
+                // Remove one-line docstring, otherwise we can't embed this.
+                example_lines.remove(0);
+            }
+        }
+
+        // Remove leading blank lines:
+        while example_lines.first() == Some(&String::default()) {
+            example_lines.remove(0);
+        }
+
+        for line in &example_lines {
+            assert!(
+                !line.contains("```"),
+                "Example {name:?} contains ``` in it, so we can't embed it in the Python API docs."
+            );
+            assert!(
+                !line.contains("\"\"\""),
+                "Example {name:?} contains \"\"\" in it, so we can't embed it in the Python API docs."
+            );
+        }
+
         if let Some(title) = title {
             lines.push(format!("### {title}:"));
         } else {
             lines.push(format!("### `{name}`:"));
         }
         lines.push("```python".into());
-        lines.extend(example.lines.into_iter());
+        lines.extend(example_lines.into_iter());
         lines.push("```".into());
         if let Some(image) = &image {
             lines.extend(image.image_stack());
@@ -930,6 +958,13 @@ fn quote_doc_lines(lines: Vec<String>) -> String {
         return String::new();
     }
 
+    for line in &lines {
+        assert!(
+            !line.contains("\"\"\""),
+            "Cannot put triple quotes in Python docstrings"
+        );
+    }
+
     // NOTE: Filter out docstrings within docstrings, it just gets crazy otherwise…
     let lines: Vec<String> = lines
         .into_iter()

crates/re_types_builder/src/codegen/rust/api.rs

@@ -452,7 +452,14 @@ impl quote::ToTokens for ObjectFieldTokenizer<'_> {
 }
 
 fn quote_field_docs(reporter: &Reporter, field: &ObjectField) -> TokenStream {
-    let lines = doc_as_lines(reporter, &field.virtpath, &field.fqname, &field.docs);
+    let require_example = false;
+    let lines = doc_as_lines(
+        reporter,
+        &field.virtpath,
+        &field.fqname,
+        &field.docs,
+        require_example,
+    );
 
     let require_field_docs = false;
     if require_field_docs && lines.is_empty() && !field.is_testing() {
@@ -463,7 +470,14 @@ fn quote_field_docs(reporter: &Reporter, field: &ObjectField) -> TokenStream {
 }
 
 fn quote_obj_docs(reporter: &Reporter, obj: &Object) -> TokenStream {
-    let mut lines = doc_as_lines(reporter, &obj.virtpath, &obj.fqname, &obj.docs);
+    let require_example = obj.kind == ObjectKind::Archetype;
+    let mut lines = doc_as_lines(
+        reporter,
+        &obj.virtpath,
+        &obj.fqname,
+        &obj.docs,
+        require_example,
+    );
 
     // Prefix first line with `**Datatype**: ` etc:
     if let Some(first) = lines.first_mut() {
@@ -475,14 +489,24 @@ fn quote_obj_docs(reporter: &Reporter, obj: &Object) -> TokenStream {
     quote_doc_lines(&lines)
 }
 
-fn doc_as_lines(reporter: &Reporter, virtpath: &str, fqname: &str, docs: &Docs) -> Vec<String> {
+fn doc_as_lines(
+    reporter: &Reporter,
+    virtpath: &str,
+    fqname: &str,
+    docs: &Docs,
+    require_example: bool,
+) -> Vec<String> {
     let mut lines = crate::codegen::get_documentation(docs, &["rs", "rust"]);
 
     let examples = collect_examples_for_api_docs(docs, "rs", true)
         .map_err(|err| reporter.error(virtpath, fqname, err))
         .unwrap_or_default();
 
-    if !examples.is_empty() {
+    if examples.is_empty() {
+        if require_example {
+            reporter.warn(virtpath, fqname, "Missing example");
+        }
+    } else {
         lines.push(Default::default());
         let section_title = if examples.len() == 1 {
             "Example"
@@ -497,14 +521,27 @@ fn doc_as_lines(reporter: &Reporter, virtpath: &str, fqname: &str, docs: &Docs)
                 name, title, image, ..
             } = &example.base;
 
+            for line in &example.lines {
+                if line.contains("```") {
+                    reporter.error(
+                        virtpath,
+                        fqname,
+                        format!("Example {name:?} contains ``` in it, so we can't embed it in the Rust API docs."),
+                    );
+                    continue;
+                }
+            }
+
             if let Some(title) = title {
                 lines.push(format!("### {title}"));
             } else {
                 lines.push(format!("### `{name}`:"));
             }
+
             lines.push("```ignore".into());
             lines.extend(example.lines.into_iter());
             lines.push("```".into());
+
             if let Some(image) = &image {
                 lines.extend(image.image_stack().into_iter());
             }

docs/code-examples/text_document.cpp

@@ -29,13 +29,6 @@ Basic formatting:
 
 ----------------------------------
 
-Some code:
-```rs
-fn main() {
-    println!("Hello, world!");
-}
-```
-
 ## Support
 - [x] [Commonmark](https://commonmark.org/help/) support
 - [x] GitHub-style strikethrough, tables, and checkboxes

docs/code-examples/text_document.py

@@ -1,4 +1,3 @@
-#!/usr/bin/env python3
 """Log a `TextDocument`."""
 
 import rerun as rr
@@ -10,7 +9,7 @@
 rr.log(
     "markdown",
     rr.TextDocument(
-        """
+        '''
 # Hello Markdown!
 [Click here to see the raw text](recording://markdown.Text).
 
@@ -26,13 +25,6 @@
 
 ----------------------------------
 
-Some code:
-```rs
-fn main() {
-    println!("Hello, world!");
-}
-```
-
 ## Support
 - [x] [Commonmark](https://commonmark.org/help/) support
 - [x] GitHub-style strikethrough, tables, and checkboxes
@@ -51,7 +43,7 @@
 
 ## Image
 ![A random image](https://picsum.photos/640/480)
-""".strip(),
+'''.strip(),
         media_type=rr.MediaType.MARKDOWN,
     ),
 )

docs/code-examples/text_document.rs

@@ -28,13 +28,6 @@ Basic formatting:
 
 ----------------------------------
 
-Some code:
-```rs
-fn main() {
-    println!("Hello, world!");
-}
-```
-
 ## Support
 - [x] [Commonmark](https://commonmark.org/help/) support
 - [x] GitHub-style strikethrough, tables, and checkboxes