allow example to live closer to content

Author: rmorshea

docs/examples.py

@@ -35,8 +35,16 @@ def load_one_example(file_or_name: Path | str) -> Callable[[], ComponentType]:
     )
 
 
+def get_normalized_example_name(
+    name: str, relative_to: str | Path | None = SOURCE_DIR
+) -> str:
+    return "/".join(
+        _get_root_example_path_by_name(name, relative_to).relative_to(SOURCE_DIR).parts
+    )
+
+
 def get_main_example_file_by_name(
-    name: str, relative_to: str | Path = SOURCE_DIR
+    name: str, relative_to: str | Path | None = SOURCE_DIR
 ) -> Path:
     path = _get_root_example_path_by_name(name, relative_to)
     if path.is_dir():
@@ -46,7 +54,7 @@ def get_main_example_file_by_name(
 
 
 def get_example_files_by_name(
-    name: str, relative_to: str | Path = SOURCE_DIR
+    name: str, relative_to: str | Path | None = SOURCE_DIR
 ) -> list[Path]:
     path = _get_root_example_path_by_name(name, relative_to)
     if path.is_dir():
@@ -58,9 +66,10 @@ def get_example_files_by_name(
 
 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:
+        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 path
 
 
@@ -118,8 +127,8 @@ def PrintView():
     return Wrapper()
 
 
-def _get_root_example_path_by_name(name: str, relative_to: str | Path) -> Path:
-    if not name.startswith("/"):
+def _get_root_example_path_by_name(name: str, relative_to: str | Path | None) -> Path:
+    if not name.startswith("/") and relative_to is not None:
         rel_path = Path(relative_to)
         rel_path = rel_path.parent if rel_path.is_file() else rel_path
     else:

docs/source/_examples/show_click_event.py

@@ -1,15 +1,18 @@
 import os
 
 from docutils.nodes import raw
-from docutils.parsers.rst import Directive, directives
+from docutils.parsers.rst import directives
 from sphinx.application import Sphinx
+from sphinx.util.docutils import SphinxDirective
+
+from docs.examples import get_normalized_example_name
 
 
 _IDOM_EXAMPLE_HOST = os.environ.get("IDOM_DOC_EXAMPLE_SERVER_HOST", "")
 _IDOM_STATIC_HOST = os.environ.get("IDOM_DOC_STATIC_SERVER_HOST", "/docs").rstrip("/")
 
 
-class IteractiveWidget(Directive):
+class IteractiveWidget(SphinxDirective):
 
     has_content = False
     required_arguments = 1
@@ -23,7 +26,11 @@ class IteractiveWidget(Directive):
     def run(self):
         IteractiveWidget._next_id += 1
         container_id = f"idom-widget-{IteractiveWidget._next_id}"
-        view_id = self.arguments[0]
+        view_id = get_normalized_example_name(
+            self.arguments[0],
+            # only used if example name starts with "/"
+            self.get_source_info()[0],
+        )
         return [
             raw(
                 "",

docs/source/_examples/simple_and_gate.py

@@ -10,7 +10,11 @@
 from sphinx.util.docutils import SphinxDirective
 from sphinx_design.tabs import TabSetDirective
 
-from docs.examples import SOURCE_DIR, get_example_files_by_name
+from docs.examples import (
+    SOURCE_DIR,
+    get_example_files_by_name,
+    get_normalized_example_name,
+)
 
 
 class WidgetExample(SphinxDirective):
@@ -25,16 +29,17 @@ class WidgetExample(SphinxDirective):
     }
 
     def run(self):
-        example_name = self.arguments[0]
+        example_name = get_normalized_example_name(
+            self.arguments[0],
+            # only used if example name starts with "/"
+            self.get_source_info()[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,
-            # only used if example name starts with "/"
-            relative_to=self.get_source_info()[0],
-        )
+        ex_files = get_example_files_by_name(example_name)
         if not ex_files:
             src_file, line_num = self.get_source_info()
             raise ValueError(
@@ -162,7 +167,7 @@ def _interactive_widget(name, with_activate_button):
 
 
 _literal_include_template = """
-.. literalinclude:: /_examples/{name}
+.. literalinclude:: /{name}
     :language: {language}
     {options}
 """