allow example to be organized into folders

Author: rmorshea

docs/Dockerfile

@@ -31,6 +31,7 @@ RUN pip install -e .[all]
 # --------------
 ADD docs/main.py ./docs/
 ADD docs/source ./docs/source
+ADD examples ./examples
 
 RUN pip install -r requirements/build-docs.txt
 RUN sphinx-build -b html docs/source docs/build
@@ -40,4 +41,4 @@ RUN sphinx-build -b html docs/source docs/build
 ENV PORT 5000
 ENV IDOM_DEBUG_MODE=1
 ENV IDOM_CHECK_VDOM_SPEC=0
-CMD python docs/main.py
+CMD python -c "import docs; docs.run()"

docs/__init__.py

@@ -0,0 +1,4 @@
+from .app import run
+
+
+__all__ = ["run"]

docs/app.py

@@ -0,0 +1,61 @@
+import os
+from logging import getLogger
+from pathlib import Path
+
+from sanic import Sanic, response
+
+from idom.config import IDOM_WED_MODULES_DIR
+from idom.server.sanic import PerClientStateServer
+from idom.widgets import multiview
+
+from .examples import load_examples
+
+
+HERE = Path(__file__).parent
+IDOM_MODEL_SERVER_URL_PREFIX = "/_idom"
+
+logger = getLogger(__name__)
+
+
+IDOM_MODEL_SERVER_URL_PREFIX = "/_idom"
+
+
+def run():
+    app = make_app()
+
+    PerClientStateServer(
+        make_examples_component(),
+        {
+            "redirect_root_to_index": False,
+            "url_prefix": IDOM_MODEL_SERVER_URL_PREFIX,
+        },
+        app,
+    )
+
+    app.run(
+        host="0.0.0.0",
+        port=int(os.environ.get("PORT", 5000)),
+        workers=int(os.environ.get("WEB_CONCURRENCY", 1)),
+        debug=bool(int(os.environ.get("DEBUG", "0"))),
+    )
+
+
+def make_app():
+    app = Sanic(__name__)
+    app.static("/docs", str(HERE / "build"))
+    app.static("/_modules", str(IDOM_WED_MODULES_DIR.current))
+
+    @app.route("/")
+    async def forward_to_index(request):
+        return response.redirect("/docs/index.html")
+
+    return app
+
+
+def make_examples_component():
+    mount, component = multiview()
+
+    for example_name, example_component in load_examples():
+        mount.add(example_name, example_component)
+
+    return component

docs/examples.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from pathlib import Path
+from traceback import format_exc
+from typing import Callable, Iterator
+
+import idom
+from idom import ComponentType
+
+
+HERE = Path(__file__)
+EXAMPLES_DIR = HERE.parent / "source" / "_examples"
+RUN_IDOM = idom.run
+
+
+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)
+
+
+def all_example_names() -> set[str]:
+    return {get_example_name_from_file(file) for file in EXAMPLES_DIR.rglob("*.py")}
+
+
+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)
+    else:
+        file = file_or_name
+
+    if not file.exists():
+        raise FileNotFoundError(str(file))
+
+    captured_component_constructor = None
+
+    def capture_component(component_constructor):
+        nonlocal captured_component_constructor
+        captured_component_constructor = component_constructor
+
+    idom.run = capture_component
+    try:
+        code = compile(file.read_text(), str(file.absolute()), "exec")
+        exec(code, {})
+    except Exception:
+        return _make_error_display()
+    finally:
+        idom.run = RUN_IDOM
+
+    if captured_component_constructor is None:
+        return _make_example_did_not_run(str(file))
+    else:
+        return captured_component_constructor
+
+
+def get_example_name_from_file(file: Path) -> str:
+    return ".".join(file.relative_to(EXAMPLES_DIR).with_suffix("").parts)
+
+
+def get_py_example_file_by_name(name: str) -> Path:
+    return EXAMPLES_DIR.joinpath(*name.split(".")).with_suffix(".py")
+
+
+def get_js_example_file_by_name(name: str) -> Path:
+    return EXAMPLES_DIR.joinpath(*name.split(".")).with_suffix(".js")
+
+
+def _make_example_did_not_run(example_name):
+    @idom.component
+    def ExampleDidNotRun():
+        return idom.html.code(f"Example {example_name} did not run")
+
+    return ExampleDidNotRun
+
+
+def _make_error_display():
+    @idom.component
+    def ShowError():
+        return idom.html.pre(format_exc())
+
+    return ShowError

docs/main.py

@@ -0,0 +1,15 @@
+from idom import component, html, run
+
+
+@component
+def App():
+    return html.div(
+        html.h1("My Todo List"),
+        html.ul(
+            html.li("Build a cool new app"),
+            html.li("Share it with the world!"),
+        ),
+    )
+
+
+run(App)

docs/source/_examples/creating_interfaces/static_todo_list.py

@@ -6,9 +6,11 @@
 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__).parent
-examples = here.parent / "_examples"
+
+HERE = Path(__file__)
+EXAMPLES_DIR = HERE.parent.parent / "_examples"
 
 
 class WidgetExample(SphinxDirective):
@@ -29,16 +31,16 @@ 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 = examples / f"{example_name}.py"
+        py_ex_path = get_py_example_file_by_name(example_name)
         if not py_ex_path.exists():
             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}"
             )
 
         labeled_tab_items = {
-            "python": _literal_include_py(
-                name=example_name,
+            "python": _literal_include(
+                name=str(py_ex_path.relative_to(EXAMPLES_DIR)),
                 linenos=show_linenos,
             ),
             "result": _interactive_widget(
@@ -53,9 +55,10 @@ def run(self):
             "result": "▶️ Result",
         }
 
-        if (examples / f"{example_name}.js").exists():
-            labeled_tab_items["javascript"] = _literal_include_js(
-                name=example_name,
+        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,
             )
 
@@ -94,20 +97,17 @@ def _make_tab_items(labeled_content_tuples):
     return _string_to_nested_lines(tab_items)
 
 
-def _literal_include_py(name, linenos):
-    return _literal_include_template.format(
-        name=name,
-        ext="py",
-        language="python",
-        linenos=":linenos:" if linenos else "",
-    )
-
+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_js(name, linenos):
     return _literal_include_template.format(
         name=name,
-        ext="js",
-        language="javascript",
+        language=language,
         linenos=":linenos:" if linenos else "",
     )
 
@@ -133,7 +133,7 @@ def _interactive_widget(name, with_activate_button):
 
 
 _literal_include_template = """
-.. literalinclude:: /_examples/{name}.{ext}
+.. literalinclude:: /_examples/{name}
     :language: {language}
     {linenos}
 """