better example presentation

Author: rmorshea

docs/examples.py

@@ -22,7 +22,7 @@ def load_examples() -> Iterator[tuple[str, Callable[[], ComponentType]]]:
 
 def all_example_names() -> set[str]:
     names = set()
-    for file in _iter_example_files():
+    for file in _iter_example_files(SOURCE_DIR):
         path = file.parent if file.name == "app.py" else file
         names.add("/".join(path.relative_to(SOURCE_DIR).with_suffix("").parts))
     return names
@@ -64,12 +64,12 @@ def get_example_files_by_name(
         return [path] if path.exists() else []
 
 
-def _iter_example_files() -> Iterator[Path]:
-    for path in SOURCE_DIR.iterdir():
+def _iter_example_files(root: Path) -> Iterator[Path]:
+    for path in root.iterdir():
         if path.is_dir():
             if not path.name.startswith("_") or path.name == "_examples":
-                yield from path.rglob("*.py")
-        elif path != CONF_FILE and path.suffix == ".py":
+                yield from _iter_example_files(path)
+        elif path.suffix == ".py" and path != CONF_FILE:
             yield path
 
 

scripts/one_example.py

@@ -46,33 +46,63 @@ def update_component():
 
 def _example_name_input() -> str:
     if len(sys.argv) == 1:
-        print("No example argument given. Provide an example's number or name:")
-        _print_available_options()
+        _print_error(
+            "No example argument given. Provide an example's number from above."
+        )
         sys.exit(1)
 
-    ex_name = sys.argv[1]
-
-    if ex_name in EXAMPLE_NAME_SET:
-        return ex_name
+    ex_num = sys.argv[1]
 
     try:
-        ex_num = int(ex_name)
+        ex_num = int(ex_num)
     except ValueError:
-        print(f"No example {ex_name!r} exists. Provide an example's number or name:")
-        _print_available_options()
+        _print_error(
+            f"No example {ex_num!r} exists. Provide an example's number as an integer."
+        )
         sys.exit(1)
 
     ex_index = ex_num - 1
     try:
         return EXAMPLE_NAME_LIST[ex_index]
     except IndexError:
-        print(f"No example #{ex_num} exists.")
+        _print_error(f"No example #{ex_num} exists. Choose from an option above.")
         sys.exit(1)
 
 
+def _print_error(*args) -> None:
+    _print_available_options()
+    print(*args)
+
+
 def _print_available_options():
+    examples_by_path = {}
     for i, name in enumerate(EXAMPLE_NAME_LIST):
-        print(f"{i + 1}.", name)
+        if "/" not in name:
+            path = ""
+        else:
+            path, name = name.rsplit("/", 1)
+        examples_by_path.setdefault(path, []).append(name)
+
+    number = 1
+    print()
+    for path, names in examples_by_path.items():
+        title = " ".join(
+            map(
+                str.title,
+                path.replace("/_examples", "")
+                .replace("/", " > ")
+                .replace("-", " ")
+                .replace("_", " ")
+                .upper()
+                .split(),
+            )
+        )
+        print(title)
+        print("-" * len(title))
+        for name in names:
+            print(f"{number}. ", name)
+            number += 1
+        print()
 
 
 if __name__ == "__main__":