Move example description to README frontmatter

.github/workflows/reusable_checks.yml

@@ -252,7 +252,7 @@ jobs:
 
       - name: Install dependencies
         run: |
-          pip install gitignore_parser
+          pip install gitignore_parser python-frontmatter
 
       - name: Rerun lints
         run: |
@@ -338,4 +338,3 @@ jobs:
       - name: Build code examples
         shell: bash
         run: ./tests/cpp/build_all_doc_examples.sh --werror
-

examples/python/arkit_scenes/README.md

@@ -2,6 +2,7 @@
 title: ARKit Scenes
 python: https://github.com/rerun-io/rerun/blob/latest/examples/python/arkit_scenes/main.py
 tags: [2D, 3D, depth, mesh, object-detection, pinhole-camera]
+description: "Visualize the ARKitScenes dataset, which contains color+depth images, the reconstructed mesh and labeled bounding boxes."
 thumbnail: https://static.rerun.io/8b90a80c72b27fad289806b7e5dff0c9ac97e87c_arkit_scenes_480w.png
 ---
 

examples/python/detect_and_track_objects/README.md

@@ -2,6 +2,7 @@
 title: Detect and Track Objects
 python: https://github.com/rerun-io/rerun/tree/latest/examples/python/detect_and_track_objects/main.py
 tags: [2D, huggingface, object-detection, object-tracking, opencv]
+description: "Visualize object detection and segmentation using the Huggingface `transformers` library."
 thumbnail: https://static.rerun.io/efb301d64eef6f25e8f6ae29294bd003c0cda3a7_detect_and_track_objects_480w.png
 ---
 

examples/python/dicom_mri/README.md

@@ -2,6 +2,7 @@
 title: Dicom MRI
 python: https://github.com/rerun-io/rerun/tree/latest/examples/python/dicom_mri/main.py
 tags: [tensor, mri, dicom]
+description: "Example using a DICOM MRI scan. This demonstrates the flexible tensor slicing capabilities of the Rerun viewer."
 thumbnail: https://static.rerun.io/b8b25dd01e892e6daf5177e6fc05ff5feb19ee8d_dicom_mri_480w.png
 ---
 

examples/python/dna/README.md

@@ -0,0 +1,21 @@
+---
+title: Helix
+python: https://github.com/rerun-io/rerun/tree/latest/examples/python/dna/main.py
+thumbnail: https://static.rerun.io/ea7a9ab2f716bd37d1bbc1eabf3f55e4f526660e_helix_480w.png
+description: "Simple example of logging point and line primitives to draw a 3D helix."
+tags: [3d, api-example]
+---
+
+<picture>
+  <source media="(max-width: 480px)" srcset="https://static.rerun.io/ea7a9ab2f716bd37d1bbc1eabf3f55e4f526660e_helix_480w.png">
+  <source media="(max-width: 768px)" srcset="https://static.rerun.io/24f69d2c402af9d7d577fb5cc0c562a73201f855_helix_768w.png">
+  <source media="(max-width: 1024px)" srcset="https://static.rerun.io/31c737bd9337d8b3d060fe21670afca3fd253414_helix_1024w.png">
+  <source media="(max-width: 1200px)" srcset="https://static.rerun.io/01903730e0b840f088df574619dee6a9fb9b42f2_helix_1200w.png">
+  <img src="https://static.rerun.io/f4c375546fa9d24f7cd3a1a715ebf75b2978817a_helix_full.png" alt="">
+</picture>
+
+Simple example of logging point and line primitives to draw a 3D helix.
+
+```bash
+python examples/python/dna/main.py
+```

examples/python/human_pose_tracking/README.md

@@ -2,6 +2,7 @@
 title: Human Pose Tracking
 python: https://github.com/rerun-io/rerun/tree/latest/examples/python/human_pose_tracking/main.py
 tags: [mediapipe, keypoint-detection, 2D, 3D]
+description: "Use the MediaPipe Pose solution to detect and track a human pose in video."
 thumbnail: https://static.rerun.io/277b9c72da1d0d0ae9d221f7552dede9c4d5b2fa_human_pose_tracking_480w.png
 ---
 

examples/python/plots/README.md

@@ -2,6 +2,8 @@
 title: Plots
 python: https://github.com/rerun-io/rerun/tree/latest/examples/python/plots/main.py
 thumbnail: https://static.rerun.io/ca0c72df93d70c79b0e640fb4b7c33cdc0bfe5f4_plots_480w.png
+description: "Demonstration of various plots and charts supported by Rerun."
+tags: [2d, plots, api-example]
 ---
 
 <picture>

examples/python/structure_from_motion/README.md

@@ -2,6 +2,7 @@
 title: Structure from Motion
 python: https://github.com/rerun-io/rerun/tree/latest/examples/python/structure_from_motion/main.py
 tags: [2D, 3D, colmap, pinhole-camera, time-series]
+description: "Visualize a sparse reconstruction by COLMAP, a general-purpose Structure-from-Motion and Multi-View Stereo pipeline."
 thumbnail: https://static.rerun.io/033edff752f86bcdc9a81f7877e0b4411ff4e6c5_structure_from_motion_480w.png
 ---
 

examples/python/template/README.md

@@ -1,6 +1,7 @@
 ---
 title: Template
 tags: [kebab-case, comma, separated]
+description: "Short ~100-sign description of the example. No longer than 130 signs!"
 python: https://github.com/rerun-io/rerun/tree/latest/examples/python/template/main.py
 rust: https://github.com/rerun-io/rerun/tree/latest/examples/rust/template/src/main.rs
 ---

scripts/ci/build_demo_app.py

@@ -9,7 +9,6 @@
 import json
 import logging
 import os
-import re
 import shutil
 import subprocess
 import threading
@@ -60,8 +59,6 @@ class Example:
     def __init__(
         self,
         name: str,
-        title: str,
-        description: str,
         commit: str,
         build_args: list[str],
     ):
@@ -82,23 +79,18 @@ def __init__(
         else:
             thumbnail = None
 
-        description_html = "".join([f"<p>{segment}</p>" for segment in description.split("\n\n")])
-
-        description = extract_text_from_html(description)
-        description = re.sub(r"[\n\s]+", " ", description)
-        description = description.strip()
-
         self.path = os.path.join("examples/python", name, "main.py")
         self.name = name
-        self.title = title
-        self.description = description
+        self.title = readme.get("title")
+        self.description = readme.get("description")
+        self.summary = readme.get("summary")
         self.tags = readme.get("tags", [])
         self.demo_url = f"https://demo.rerun.io/commit/{commit}/examples/{name}/"
         self.rrd_url = f"https://demo.rerun.io/commit/{commit}/examples/{name}/data.rrd"
         self.source_url = f"https://github.com/rerun-io/rerun/tree/{commit}/examples/python/{name}/main.py"
         self.thumbnail = thumbnail
         self.build_args = build_args
-        self.description_html = description_html
+        self.description_html = "".join([f"<p>{segment}</p>" for segment in self.description.split("\n\n")])
 
     def save(self) -> None:
         in_path = os.path.abspath(self.path)
@@ -188,8 +180,6 @@ def collect_examples() -> list[Example]:
     for name in EXAMPLES.keys():
         example = Example(
             name,
-            title=EXAMPLES[name]["title"],
-            description=EXAMPLES[name]["description"],
             commit=commit,
             build_args=EXAMPLES[name]["build_args"],
         )
@@ -311,66 +301,24 @@ def main() -> None:
 # When adding examples, add their requirements to `requirements-web-demo.txt`
 EXAMPLES: dict[str, Any] = {
     "arkit_scenes": {
-        "title": "ARKit Scenes",
-        "description": """
-        Visualizes the <a href="https://github.com/apple/ARKitScenes/" target="_blank">ARKitScenes dataset</a>
-        using the Rerun SDK.
-        The dataset contains color+depth images, the reconstructed mesh and labeled bounding boxes around furniture.
-        """,
         "build_args": [],
     },
     "structure_from_motion": {
-        "title": "Structure From Motion",
-        "description": """
-        An example using Rerun to log and visualize the output of COLMAP's sparse reconstruction.
-
-        <a href="https://colmap.github.io/index.html" target="_blank">COLMAP</a>
-        is a general-purpose Structure-from-Motion (SfM)
-        and Multi-View Stereo (MVS) pipeline with a graphical and command-line interface.
-
-        In this example a short video clip has been processed offline by the COLMAP pipeline,
-        and we use Rerun to visualize the individual camera frames, estimated camera poses,
-        and resulting point clouds over time.
-        """,
         "build_args": ["--dataset=colmap_fiat", "--resize=800x600"],
     },
     "dicom_mri": {
-        "title": "Dicom MRI",
-        "description": """
-        Example using a <a href="https://en.wikipedia.org/wiki/DICOM" target="_blank">DICOM</a> MRI scan.
-        This demonstrates the flexible tensor slicing capabilities of the Rerun viewer.
-        """,
         "build_args": [],
     },
     "human_pose_tracking": {
-        "title": "Human Pose Tracking",
-        "description": """
-        Use the <a href="https://google.github.io/mediapipe/" target="_blank">MediaPipe</a> Pose
-        solution to detect and track a human pose in video.
-        """,
         "build_args": [],
     },
     "plots": {
-        "title": "Plots",
-        "description": """
-        Simple example of plots and charts.
-        """,
         "build_args": [],
     },
     "detect_and_track_objects": {
-        "title": "Detect and Track Objects",
-        "description": """
-        Applying simple object detection and segmentation on a video using the Huggingface `transformers` library.
-        Tracking across frames is performed using
-        <a href="https://arxiv.org/pdf/1611.08461.pdf" target="_blank">CSRT</a> from OpenCV.
-        """,
         "build_args": [],
     },
     "dna": {
-        "title": "Helix",
-        "description": """
-        Simple example of logging line primitives to draw a 3D helix.
-        """,
         "build_args": [],
     },
 }

scripts/lint.py

@@ -13,6 +13,7 @@
 import sys
 from typing import Any, Iterator
 
+import frontmatter
 from gitignore_parser import parse_gitignore
 
 # -----------------------------------------------------------------------------
@@ -428,6 +429,35 @@ def test_lint_forbidden_widgets() -> None:
     assert _index_to_line_nr(should_fail_two_times, res[1][1]) == 5
 
 
+def lint_example_description(filepath: str, fm: frontmatter.Post) -> list[str]:
+    # only applies to examples' readme
+
+    if not filepath.startswith("./examples/python") or not filepath.endswith("README.md"):
+        return []
+
+    desc = fm.get("description", "")
+    if len(desc) > 130:
+        return [f"Frontmatter: description is too long ({len(desc)} > 130)"]
+    else:
+        return []
+
+
+def lint_frontmatter(filepath: str, content: str) -> list[str]:
+    """Only for Markdown files."""
+
+    errors = []
+    if not filepath.endswith(".md"):
+        return errors
+
+    fm = frontmatter.loads(content)
+
+    errors += lint_example_description(filepath, fm)
+
+    # TODO(ab): check for missing fields (when descriptions are populated everywhere)
+
+    return errors
+
+
 # -----------------------------------------------------------------------------
 
 
@@ -529,6 +559,14 @@ def lint_file(filepath: str, args: Any) -> int:
         if args.fix:
             source.rewrite(lines_out)
 
+    # Markdown-specific lints
+    if filepath.endswith(".md"):
+        errors = lint_frontmatter(filepath, source.content)
+
+        for error in errors:
+            print(source.error(error))
+        num_errors += len(errors)
+
     return num_errors
 
 

scripts/requirements-dev.txt

@@ -11,3 +11,4 @@ Pillow # for scripts/upload_image.py
 tqdm
 requests
 gitignore_parser  # handle .gitignore
+python-frontmatter==1.0.0