try and make examples load relative to current file

Author: rmorshea

docs/examples.py

@@ -10,7 +10,8 @@
 
 
 HERE = Path(__file__)
-EXAMPLES_DIR = HERE.parent / "source" / "_examples"
+SOURCE_DIR = HERE.parent / "source"
+CONF_FILE = SOURCE_DIR / "conf.py"
 RUN_IDOM = idom.run
 
 
@@ -21,26 +22,48 @@ def load_examples() -> Iterator[tuple[str, Callable[[], ComponentType]]]:
 
 def all_example_names() -> set[str]:
     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))
+    for file in _iter_example_files():
+        path = file.parent if file.name == "app.py" else file
+        names.add("/".join(path.relative_to(SOURCE_DIR).with_suffix("").parts))
     return names
 
 
 def load_one_example(file_or_name: Path | str) -> Callable[[], ComponentType]:
     return lambda: (
-        # we do this to ensure each instance is fresh
+        # we use a lambda to ensure each instance is fresh
         _load_one_example(file_or_name)
     )
 
 
+def get_main_example_file_by_name(
+    name: str, relative_to: str | Path = SOURCE_DIR
+) -> Path:
+    path = _get_root_example_path_by_name(name, relative_to)
+    if path.is_dir():
+        return path / "app.py"
+    else:
+        return path.with_suffix(".py")
+
+
+def get_example_files_by_name(
+    name: str, relative_to: str | Path = SOURCE_DIR
+) -> list[Path]:
+    path = _get_root_example_path_by_name(name, relative_to)
+    if path.is_dir():
+        return list(path.glob("*"))
+    else:
+        path = path.with_suffix(".py")
+        return [path] if path.exists() else []
+
+
+def _iter_example_files() -> Iterator[Path]:
+    for path in SOURCE_DIR.iterdir():
+        if path.is_dir() and not path.name.startswith("_"):
+            yield from path.rglob("*.py")
+        elif path != CONF_FILE:
+            yield path
+
+
 def _load_one_example(file_or_name: Path | str) -> ComponentType:
     if isinstance(file_or_name, str):
         file = get_main_example_file_by_name(file_or_name)
@@ -95,25 +118,13 @@ def PrintView():
     return Wrapper()
 
 
-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_example_files_by_name(name: str) -> list[Path]:
-    path = _get_root_example_path_by_name(name)
-    if path.is_dir():
-        return list(path.glob("*"))
+def _get_root_example_path_by_name(name: str, relative_to: str | Path) -> Path:
+    if not name.startswith("/"):
+        rel_path = Path(relative_to)
+        rel_path = rel_path.parent if rel_path.is_file() else rel_path
     else:
-        path = path.with_suffix(".py")
-        return [path] if path.exists() else []
-
-
-def _get_root_example_path_by_name(name: str) -> Path:
-    return EXAMPLES_DIR.joinpath(*name.split("/"))
+        rel_path = SOURCE_DIR
+    return rel_path.joinpath(*name.split("/"))
 
 
 class _PrintBuffer:

docs/source/_exts/widget_example.py

@@ -10,7 +10,7 @@
 from sphinx.util.docutils import SphinxDirective
 from sphinx_design.tabs import TabSetDirective
 
-from docs.examples import EXAMPLES_DIR, get_example_files_by_name
+from docs.examples import SOURCE_DIR, get_example_files_by_name
 
 
 class WidgetExample(SphinxDirective):
@@ -25,13 +25,16 @@ class WidgetExample(SphinxDirective):
     }
 
     def run(self):
-        print(self.get_source_info())
         example_name = self.arguments[0]
         show_linenos = "linenos" in self.options
         live_example_is_default_tab = "result-is-default-tab" in self.options
         activate_result = "activate-result" in self.options
 
-        ex_files = get_example_files_by_name(example_name)
+        ex_files = get_example_files_by_name(
+            example_name,
+            # only used if example name starts with "/"
+            relative_to=self.get_source_info()[0],
+        )
         if not ex_files:
             src_file, line_num = self.get_source_info()
             raise ValueError(
@@ -108,7 +111,7 @@ def _literal_include(path: Path, linenos: bool):
         raise ValueError(f"Unknown extension type {path.suffix!r}")
 
     return _literal_include_template.format(
-        name=str(path.relative_to(EXAMPLES_DIR)),
+        name=str(path.relative_to(SOURCE_DIR)),
         language=language,
         options=_join_options(_get_file_options(path)),
     )
@@ -170,4 +173,4 @@ def _string_to_nested_lines(content):
 
 
 def setup(app: Sphinx) -> None:
-    app.add_directive("example", WidgetExample)
+    app.add_directive("idom", WidgetExample)