allow examples to be organized in directory

Author: rmorshea

docs/examples.py

@@ -15,17 +15,28 @@
 
 
 def load_examples() -> Iterator[tuple[str, Callable[[], ComponentType]]]:
-    for file in EXAMPLES_DIR.rglob("*.py"):
-        yield get_example_name_from_file(file), load_one_example(file)
+    for name in all_example_names():
+        yield name, load_one_example(name)
 
 
 def all_example_names() -> set[str]:
-    return {get_example_name_from_file(file) for file in EXAMPLES_DIR.rglob("*.py")}
+    names = set()
+    for file in EXAMPLES_DIR.rglob("*.py"):
+        if file.name != "app.py" and (file.parent / "app.py").exists():
+            # this isn't the main example file
+            continue
+        path = file.relative_to(EXAMPLES_DIR)
+        if path.name == "app.py":
+            path = path.parent
+        else:
+            path = path.with_suffix("")
+        names.add(".".join(path.parts))
+    return names
 
 
 def load_one_example(file_or_name: Path | str) -> Callable[[], ComponentType]:
     if isinstance(file_or_name, str):
-        file = get_py_example_file_by_name(file_or_name)
+        file = get_main_example_file_by_name(file_or_name)
     else:
         file = file_or_name
 
@@ -66,16 +77,24 @@ def Wrapper():
         return Wrapper
 
 
-def get_example_name_from_file(file: Path) -> str:
-    return ".".join(file.relative_to(EXAMPLES_DIR).with_suffix("").parts)
+def get_main_example_file_by_name(name: str) -> Path:
+    path = _get_root_example_path_by_name(name)
+    if path.is_dir():
+        return path / "app.py"
+    else:
+        return path.with_suffix(".py")
 
 
-def get_py_example_file_by_name(name: str) -> Path:
-    return EXAMPLES_DIR.joinpath(*name.split(".")).with_suffix(".py")
+def get_example_files_by_name(name: str) -> list[Path]:
+    path = _get_root_example_path_by_name(name)
+    if path.is_dir():
+        return list(path.glob("*"))
+    path = path.with_suffix(".py")
+    return [path] if path.exists() else []
 
 
-def get_js_example_file_by_name(name: str) -> Path:
-    return EXAMPLES_DIR.joinpath(*name.split(".")).with_suffix(".js")
+def _get_root_example_path_by_name(name: str) -> Path:
+    return EXAMPLES_DIR.joinpath(*name.split("."))
 
 
 def _printout_viewer():

docs/source/_examples/super_simple_chart.py renamed to docs/source/_examples/super_simple_chart/app.py

@@ -3,14 +3,13 @@
 from idom import component, run, web
 
 
-file = Path(__file__).parent / "super_simple_chart.js"
+file = Path(__file__).parent / "super-simple-chart.js"
 ssc = web.module_from_file("super-simple-chart", file, fallback="⌛")
 SuperSimpleChart = web.export(ssc, "SuperSimpleChart")
 
 
 @component
 def App():
-    print(__name__)
     return SuperSimpleChart(
         {
             "data": [

docs/source/_examples/super_simple_chart.js renamed to docs/source/_examples/super_simple_chart/super-simple-chart.js

@@ -1,16 +1,13 @@
 from pathlib import Path
+from typing import Any
 
 from docutils.parsers.rst import directives
 from docutils.statemachine import StringList
 from sphinx.application import Sphinx
 from sphinx.util.docutils import SphinxDirective
 from sphinx_design.tabs import TabSetDirective
 
-from docs.examples import get_js_example_file_by_name, get_py_example_file_by_name
-
-
-HERE = Path(__file__)
-EXAMPLES_DIR = HERE.parent.parent / "_examples"
+from docs.examples import EXAMPLES_DIR, get_example_files_by_name
 
 
 class WidgetExample(SphinxDirective):
@@ -31,54 +28,54 @@ def run(self):
         live_example_is_default_tab = "result-is-default-tab" in self.options
         activate_result = "activate-result" in self.options
 
-        py_ex_path = get_py_example_file_by_name(example_name)
-        if not py_ex_path.exists():
+        ex_files = get_example_files_by_name(example_name)
+        if not ex_files:
             src_file, line_num = self.get_source_info()
             raise ValueError(
-                f"Missing example file named {py_ex_path} referenced by document {src_file}:{line_num}"
+                f"Missing example named {example_name!r} "
+                f"referenced by document {src_file}:{line_num}"
             )
 
-        labeled_tab_items = {
-            "python": _literal_include(
-                name=str(py_ex_path.relative_to(EXAMPLES_DIR)),
-                linenos=show_linenos,
-            ),
-            "result": _interactive_widget(
+        labeled_tab_items: list[tuple[str, Any]] = []
+        if len(ex_files) == 1:
+            labeled_tab_items.append(
+                (
+                    "app.py",
+                    _literal_include(
+                        path=ex_files[0],
+                        linenos=show_linenos,
+                    ),
+                )
+            )
+        else:
+            for path in sorted(ex_files, key=lambda p: p.name):
+                labeled_tab_items.append(
+                    (
+                        path.name,
+                        _literal_include(
+                            path=path,
+                            linenos=show_linenos,
+                        ),
+                    )
+                )
+
+        result_tab_item = (
+            "▶️ result",
+            _interactive_widget(
                 name=example_name,
                 with_activate_button=not activate_result,
             ),
-        }
-
-        labeled_tab_titles = {
-            "python": "Python",
-            "javascript": "Javascript",
-            "result": "▶️ Result",
-        }
-
-        js_ex_path = get_js_example_file_by_name(example_name)
-        if js_ex_path.exists():
-            labeled_tab_items["javascript"] = _literal_include(
-                name=str(js_ex_path.relative_to(EXAMPLES_DIR)),
-                linenos=show_linenos,
-            )
-
-        tab_label_order = (
-            ["result", "python", "javascript"]
-            if live_example_is_default_tab
-            else ["python", "javascript", "result"]
         )
+        if live_example_is_default_tab:
+            labeled_tab_items.insert(0, result_tab_item)
+        else:
+            labeled_tab_items.append(result_tab_item)
 
         return TabSetDirective(
             "WidgetExample",
             [],
             {},
-            _make_tab_items(
-                [
-                    (labeled_tab_titles[label], labeled_tab_items[label])
-                    for label in tab_label_order
-                    if label in labeled_tab_items
-                ]
-            ),
+            _make_tab_items(labeled_tab_items),
             self.lineno - 1,
             self.content_offset,
             "",
@@ -97,16 +94,18 @@ def _make_tab_items(labeled_content_tuples):
     return _string_to_nested_lines(tab_items)
 
 
-def _literal_include(name, linenos):
-    if name.endswith(".py"):
-        language = "python"
-    elif name.endswith(".js"):
-        language = "javascript"
-    else:
-        raise ValueError("Unknown extension type")
+def _literal_include(path: Path, linenos: bool):
+    try:
+        language = {
+            ".py": "python",
+            ".js": "javascript",
+            ".json": "json",
+        }[path.suffix]
+    except KeyError:
+        raise ValueError(f"Unknown extension type {path.suffix!r}")
 
     return _literal_include_template.format(
-        name=name,
+        name=str(path.relative_to(EXAMPLES_DIR)),
         language=language,
         linenos=":linenos:" if linenos else "",
     )

docs/source/_exts/widget_example.py

@@ -55,7 +55,7 @@ To get a rough idea of how to write apps in IDOM, take a look at the tiny `"hell
 
 .. note::
 
-    Try clicking the **▶️ Result** tab to see what this displays!
+    Try clicking the **▶️ result** tab to see what this displays!
 
 So what exactly does this code do? First, it imports a few tools from ``idom`` that will
 get used to describe and execute an application. Then, we create an ``App`` function