fix docs after import source changes

Author: rmorshea

docs/main.py

@@ -5,10 +5,19 @@
 from sanic import Sanic, response
 
 import idom
+from idom.config import IDOM_CLIENT_IMPORT_SOURCE_URL
 from idom.server.sanic import PerClientStateServer
 from idom.widgets.utils import multiview
 
 
+IDOM_MODEL_SERVER_URL_PREFIX = "/_idom"
+
+IDOM_CLIENT_IMPORT_SOURCE_URL.set_default(
+    # set_default because scripts/live_docs.py needs to overwrite this
+    f"{IDOM_MODEL_SERVER_URL_PREFIX}{IDOM_CLIENT_IMPORT_SOURCE_URL.default}"
+)
+
+
 here = Path(__file__).parent
 
 app = Sanic(__name__)
@@ -52,7 +61,11 @@ async def forward_to_index(request):
 
 
 PerClientStateServer(
-    component, {"redirect_root_to_index": False, "url_prefix": "/_idom"}
+    component,
+    {
+        "redirect_root_to_index": False,
+        "url_prefix": IDOM_MODEL_SERVER_URL_PREFIX,
+    },
 ).register(app)
 
 

docs/source/_exts/interactive_widget.py

@@ -5,7 +5,9 @@
 from sphinx.application import Sphinx
 
 
-_IDOM_SERVER_LOC = os.environ.get("IDOM_DOC_EXAMPLE_SERVER_HOST", "")
+_IDOM_EXAMPLE_HOST = os.environ.get("IDOM_DOC_EXAMPLE_SERVER_HOST", "")
+_IDOM_EXAMPLE_PATH = os.environ.get("IDOM_DOC_EXAMPLE_SERVER_PATH", "/_idom")
+_IDOM_STATIC_HOST = os.environ.get("IDOM_DOC_STATIC_SERVER_HOST", "/docs").rstrip("/")
 
 
 class IteractiveWidget(Directive):
@@ -25,8 +27,8 @@ def run(self):
                 <div>
                     <div id="{container_id}" class="interactive widget-container center-content" style="" />
                     <script async type="module">
-                        import loadWidgetExample from "/docs/_static/js/load-widget-example.js";
-                        loadWidgetExample("{_IDOM_SERVER_LOC}", "/_idom", "{container_id}", "{view_id}");
+                        import loadWidgetExample from "{_IDOM_STATIC_HOST}/_static/js/load-widget-example.js";
+                        loadWidgetExample("{_IDOM_EXAMPLE_HOST}", "{_IDOM_EXAMPLE_PATH}", "{container_id}", "{view_id}");
                     </script>
                 </div>
                 """,

docs/source/examples/matplotlib_plot.py

@@ -28,7 +28,7 @@ def set_value_at_index(event, index=i):
             new_value = float(event["value"] or 0)
             set_values(values[:index] + [new_value] + values[index + 1 :])
 
-        inputs.append(poly_coef_input(i, set_value_at_index))
+        inputs.append(poly_coef_input(i + 1, set_value_at_index))
 
     def add_input():
         set_values(values + [0])
@@ -75,7 +75,7 @@ def poly_coef_input(index, callback):
 
 
 def polynomial(x, coefficients):
-    return sum(c * (x ** i) for i, c in enumerate(coefficients))
+    return sum(c * (x ** (i + 1)) for i, c in enumerate(coefficients))
 
 
 def linspace(start, stop, n):

docs/source/examples/simple_dashboard.py

@@ -53,7 +53,15 @@ async def animate():
         }
         set_data(data[1:] + [next_data_point])
 
-    return victory.VictoryLine({"data": data, "style": {"parent": {"width": "500px"}}})
+    return victory.VictoryLine(
+        {
+            "data": data,
+            "style": {
+                "parent": {"width": "500px"},
+                "data": {"stroke": "#c43a31"},
+            },
+        }
+    )
 
 
 @idom.component

docs/source/examples/victory_chart.py

@@ -2,9 +2,5 @@
 
 
 victory = idom.install("victory", fallback="loading...")
-
-idom.run(
-    idom.component(
-        lambda: victory.VictoryBar({"style": {"parent": {"width": "500px"}}}),
-    )
-)
+bar_style = {"parent": {"width": "500px"}, "data": {"fill": "#c43a31"}}
+idom.run(idom.component(lambda: victory.VictoryBar({"style": bar_style})))

docs/source/package-api.rst

@@ -54,7 +54,7 @@ Flask Servers
 
 
 FastAPI Servers
--------------
+---------------
 
 .. automodule:: idom.server.fastapi
     :members:

noxfile.py

@@ -64,7 +64,7 @@ def docs(session: Session) -> None:
         "html",
         "docs/source",
         "docs/build",
-        env={"PYTHONPATH": os.getcwd()},
+        env={"PYTHONPATH": os.getcwd(), "IDOM_DEBUG_MODE": "1"},
     )
 
 

scripts/live_docs.py

@@ -10,10 +10,15 @@
     get_parser,
 )
 
+from idom.config import IDOM_CLIENT_IMPORT_SOURCE_URL
 from idom.server.sanic import PerClientStateServer
 
 
-os.environ["IDOM_DOC_EXAMPLE_SERVER_HOST"] = "127.0.0.1:5555"
+# these environment variable are used in custom Sphinx extensions
+os.environ["IDOM_DOC_EXAMPLE_SERVER_HOST"] = example_server_host = "127.0.0.1:5555"
+os.environ["IDOM_DOC_EXAMPLE_SERVER_PATH"] = ""
+os.environ["IDOM_DOC_STATIC_SERVER_HOST"] = ""
+
 _running_idom_servers = []
 
 
@@ -22,13 +27,16 @@ def wrap_builder(old_builder):
     def new_builder():
         [s.stop() for s in _running_idom_servers]
 
+        # we need to set this before `docs.main` does
+        IDOM_CLIENT_IMPORT_SOURCE_URL.set(
+            f"http://{example_server_host}{IDOM_CLIENT_IMPORT_SOURCE_URL.default}"
+        )
+
         from docs import main
 
         importlib.reload(main)
 
-        server = PerClientStateServer(
-            main.component, {"cors": True, "url_prefix": "_idom"}
-        )
+        server = PerClientStateServer(main.component, {"cors": True})
         _running_idom_servers.append(server)
         server.daemon("127.0.0.1", 5555, debug=True)
         old_builder()

src/idom/_option.py

@@ -1,10 +1,12 @@
 from __future__ import annotations
 
 import os
+from logging import getLogger
 from typing import Any, Callable, Generic, TypeVar, cast
 
 
 _O = TypeVar("_O")
+logger = getLogger(__name__)
 
 
 class Option(Generic[_O]):
@@ -17,11 +19,18 @@ def __init__(
         mutable: bool = True,
         validator: Callable[[Any], _O] = lambda x: cast(_O, x),
     ) -> None:
-        self.name = name
+        self._name = name
         self._default = default
         self._mutable = mutable
         self._validator = validator
-        self._value = validator(os.environ.get(name, default))
+        if name in os.environ:
+            self._value = validator(os.environ[name])
+        logger.debug(f"{self._name}={self.get()}")
+
+    @property
+    def name(self) -> str:
+        """The name of this option (used to load environment variables)"""
+        return self._name
 
     @property
     def mutable(self) -> bool:
@@ -33,24 +42,48 @@ def default(self) -> _O:
         """This option's default value"""
         return self._default
 
+    def is_set(self) -> bool:
+        """Whether this option has a value other than its default."""
+        return hasattr(self, "_value")
+
     def get(self) -> _O:
         """Get the current value of this option."""
-        return self._value
+        return getattr(self, "_value", self._default)
 
-    def set(self, new: _O) -> _O:
-        """Set the value of this configuration option
+    def set(self, new: _O) -> None:
+        """Set the value of this option
 
         Raises a ``TypeError`` if this option is not :attr:`Option.mutable`.
         """
         if not self._mutable:
             raise TypeError(f"{self} cannot be modified after initial load")
-        old = self._value
         self._value = self._validator(new)
-        return old
+        logger.debug(f"{self._name}={self._value}")
+
+    def set_default(self, new: _O) -> _O:
+        """Set the value of this option if :meth:`Option.is_default`
+
+        Returns the current value (a la :meth:`dict.set_default`)
+        """
+        if not hasattr(self, "_value"):
+            self.set(new)
+        return self._value
 
-    def reset(self) -> _O:
-        """Reset the value of this option to its default setting"""
-        return self.set(self._default)
+    def reload(self) -> None:
+        """Reload this option from its environment variable
+
+        Returns the old value of the option.
+        """
+        self.set(os.environ.get(self._name, self._default))
+
+    def reset(self) -> None:
+        """Reset the value of this option to its default setting
+
+        Returns the old value of the option.
+        """
+        if not self._mutable:
+            raise TypeError(f"{self} cannot be modified after initial load")
+        delattr(self, "_value")
 
     def __repr__(self) -> str:
-        return f"Option({self.name}={self._value!r})"
+        return f"Option({self._name}={self.get()!r})"

tests/test__option.py

@@ -8,6 +8,7 @@
 
 def test_option_repr():
     opt = Option("A_FAKE_OPTION", "some-value")
+    assert opt.name == "A_FAKE_OPTION"
     assert repr(opt) == "Option(A_FAKE_OPTION='some-value')"
 
 
@@ -41,16 +42,35 @@ def test_immutable_option():
     assert not opt.mutable
     with pytest.raises(TypeError, match="cannot be modified after initial load"):
         opt.set("a-new-value")
+    with pytest.raises(TypeError, match="cannot be modified after initial load"):
+        opt.reset()
 
 
 def test_option_reset():
     opt = Option("A_FAKE_OPTION", "default-value")
     opt.set("a-new-value")
-    assert opt.get() == "a-new-value"
     opt.reset()
     assert opt.get() is opt.default
+    assert not opt.is_set()
+
+
+@mock.patch.dict(os.environ, {"A_FAKE_OPTION": "value-from-environ"})
+def test_option_reload():
+    opt = Option("A_FAKE_OPTION", "default-value")
+    opt.set("some-other-value")
+    opt.reload()
+    assert opt.get() == "value-from-environ"
+
+
+def test_option_set():
+    opt = Option("A_FAKE_OPTION", "default-value")
+    assert not opt.is_set()
+    opt.set("a-new-value")
+    assert opt.is_set()
 
 
-def test_option_set_returns_last_value():
+def test_option_set_default():
     opt = Option("A_FAKE_OPTION", "default-value")
-    assert opt.set("a-new-value") == "default-value"
+    assert not opt.is_set()
+    assert opt.set_default("new-value") == "new-value"
+    assert opt.is_set()