more doc updates

Author: rmorshea

docs/source/core-concepts.rst

@@ -19,9 +19,9 @@ the addage "the best code is no code at all," we make the related claim that "th
 way to manage state is to have no state at all."
 
 With IDOM the core of your application will be built on the back of basic functions and
-coroutines that return :term:`VDOM` models and which do so without state and without
-`side effects`_. We call these kinds of model rendering functions
-:term:`Pure Elements <Pure Element>`. For example, one might want a function which
+coroutines that return :ref:`VDOM <VDOM Mimetype>` models and which do so without state
+and without `side effects`_. We call these kinds of model rendering functions
+:ref:`Pure Elements`. For example, one might want a function which
 accepted a list of strings and turned it into a series of paragraph elements:
 
 .. code-block::
@@ -33,7 +33,7 @@ accepted a list of strings and turned it into a series of paragraph elements:
 Stateful Elements
 -----------------
 
-A Stateful Element is one which uses a :ref:`Life Cycle Hook`. These life cycle hooks
+A Stateful Element is one which uses a :ref:`Life Cycle Hooks`. These life cycle hooks
 allow you to add state to otherwise stateless functions. To create a stateful element
 you'll need to apply the :func:`~idom.core.element.element` decorator to a coroutine_
 whose body contains a hook usage. We'll demonstrate that with a simple
@@ -57,9 +57,9 @@ whose body contains a hook usage. We'll demonstrate that with a simple
 Element Layout
 --------------
 
-Displaying an element requires you to turn elements into :term:`VDOM` - this is done
-using a :class:`~idom.core.layout.Layout`. Layouts are responsible for rendering
-elements (turning them into VDOM) and scheduling their re-renders when they
+Displaying an element requires you to turn elements into :ref:`VDOM <VDOM Mimetype>` -
+this is done using a :class:`~idom.core.layout.Layout`. Layouts are responsible for
+rendering elements (turning them into VDOM) and scheduling their re-renders when they
 :meth:`~idom.core.layout.Layout.update`. To create a layout, you'll need an
 :class:`~idom.core.element.Element` instance, which will become its root, and won't
 ever be removed from the model. Then you'll just need to call and await a

docs/source/examples.rst

@@ -167,12 +167,12 @@ Source of ``chart.js``:
 Shared Client Views
 -------------------
 
-This example requires the :ref:`~idom.server.sanic.SharedClientStateServer`. Be sure to
-replace it in your boilerplate code before going further! Once you've done this we can
-just re-display our :ref:`Slideshow` example using the new server. Now all we need to do
-is connect to the server with a couple clients to see that their views are synced. This
-can be done by navigating to the server URL in seperate browser tabs. Likewise if you're
-using a Jupyter Notebook you would display it in multiple cells like this:
+This example requires the :class:`~idom.server.sanic.SharedClientStateServer`. Be sure
+to replace it in your boilerplate code before going further! Once you've done this we
+can just re-display our :ref:`Slideshow` example using the new server. Now all we need
+to do is connect to the server with a couple clients to see that their views are synced.
+This can be done by navigating to the server URL in seperate browser tabs. Likewise if
+you're using a Jupyter Notebook you would display it in multiple cells like this:
 
 **Jupyter Notebook**
 

docs/source/examples/custom_chart.py

@@ -20,31 +20,19 @@
 
 @idom.element
 async def ShowChartClicks():
-    shared_last_event = idom.hooks.Shared({})
-    idom.html.div(
-        ClickableChart(shared_last_event),
-        LastEventView(shared_last_event),
-    )
-
-
-@idom.element
-async def Chart(shared_last_event):
-    set_last_event = idom.hooks.use_state(shared_last_event)[1]
-
-    async def log_event(event):
-        set_last_event(event)
-
-    return ClickableChart(
-        {"data": data, "onClick": log_event, "style": {"parent": {"width": "500px"}}},
-    )
-
-
-@idom.element
-async def LastEventView(shared_last_event):
-    last_event = idom.hooks.use_state(shared_last_event)[0]
-
+    last_event, set_last_event = idom.hooks.use_state({})
     return idom.html.div(
-        {"class": "highlight"}, idom.html.pre(json.dumps(last_event, indent=2))
+        ClickableChart(
+            {
+                "data": data,
+                "onClick": set_last_event,
+                "style": {"parent": {"width": "500px"}},
+            },
+        ),
+        idom.html.div(
+            {"class": "highlight"},
+            idom.html.pre(json.dumps(last_event, indent=2)),
+        ),
     )
 
 

docs/source/examples/primary_secondary_buttons.py

@@ -18,7 +18,7 @@ def pre_seperated(*args):
 
 
 @idom.element
-async def PrimarySecondaryButtons(self):
+async def PrimarySecondaryButtons():
     state, set_state = idom.hooks.use_state(
         {"message": None, "event": None, "info": None}
     )

docs/source/examples/snake_game.py

@@ -82,7 +82,7 @@ async def on_direction_change(event):
         assign_grid_block_color(grid, snake[-1], "yellow")
         set_game_state(GameState.won)
 
-    interval = use_interval(0.4)
+    interval = use_interval(0.5)
 
     @use_async_effect
     async def animate():

docs/source/getting-started.rst

@@ -13,7 +13,7 @@ Let's look at the example that you may have seen
     async def Slideshow():
         index, set_index = idom.hooks.use_state(0)
 
-        async def next_image(event):
+        def next_image(event):
             set_index(index + 1)
 
         return idom.html.img(
@@ -36,7 +36,7 @@ Since it's likely a lot to take in at once, we'll break it down piece by piece:
    @idom.element
    async def Slideshow():
 
-The ``idom.element`` decorator creates an :ref:`Element <Stateful Element>` constructor
+The ``idom.element`` decorator creates an :ref:`Element <Stateful Elements>` constructor
 whose render function is defined by the `asynchronous function`_ below it. To create
 an :class:`~idom.core.element.Element` instance we call ``Slideshow()`` with the same
 arguments as its render function. The render function of an Element returns a data
@@ -68,7 +68,7 @@ function allow us to change it. The one required argument of ``use_state`` is th
 
 .. code-block::
 
-        async def next_image(event):
+        def next_image(event):
             set_index(index + 1)
 
 The coroutine above will get added as an event handler to the resulting view. When it

docs/source/glossary.rst

@@ -15,11 +15,9 @@ Libraries for defining and controlling interactive webpages with Python
     core-concepts
     life-cycle-hooks
     javascript-modules
-    how-it-works
     specifications
     extra-features
     examples
-    glossary
     known-issues
     api
 
@@ -53,7 +51,7 @@ user clicks an image:
     async def Slideshow():
         index, set_index = idom.hooks.use_state(0)
 
-        async def next_image(event):
+        def next_image(event):
             set_index(index + 1)
 
         return idom.html.img(

docs/source/index.rst

@@ -187,7 +187,7 @@ one state to the next is especially complex or involves nested data structures.
 may be slightly more performant as well as being preferable since there is only one
 ``dispatch_action`` callback versus the many ``set_state`` callbacks.
 
-We can rework the :ref:`Function Updates` counter example to use ``use_reducer``:
+We can rework the :ref:`Functional Updates` counter example to use ``use_reducer``:
 
 .. literalinclude:: examples/use_reducer_counter.py
 

docs/source/life-cycle-hooks.rst

@@ -2,8 +2,9 @@ Specifications
 ==============
 
 Describes various data structures and protocols used to define and communicate virtual
-document object models (:term:`VDOM`). The definitions to below follow in the footsteps
-of `a specification <https://github.com/nteract/vdom/blob/master/docs/mimetype-spec.md>`_
+document object models (:ref:`VDOM <VDOM Mimetype>`). The definitions to below follow in
+the footsteps of
+`a specification <https://github.com/nteract/vdom/blob/master/docs/mimetype-spec.md>`_
 created by `Nteract <https://nteract.io>`_ and which was built into
 `JupyterLab <https://jupyterlab.readthedocs.io/en/stable/>`_. While IDOM's specification
 for VDOM is fairly well established, it should not be relied until it's been fully
@@ -167,4 +168,6 @@ Updates to VDOM modules are sent using the `JSON Patch`_ specification.
 ... this section is still under construction :)
 
 
-.. _JSON Patch:: http://jsonpatch.com/
+.. Links
+.. =====
+.. _JSON Patch: http://jsonpatch.com/

docs/source/specifications.rst

@@ -147,7 +147,6 @@ def _package_json() -> Dict[str, Any]:
         "snowpack": {
             "installOptions": {
                 "dest": str(WEB_MODULES),
-                "include": str(CORE_MODULES / "**" / "*.js"),
             },
             "webDependencies": [],
         },

idom/client/manage.py

@@ -18,7 +18,7 @@ def element(function: ElementRenderFunction) -> Callable[..., "Element"]:
 
     Parameters:
         function:
-            The function that will render a :term:`VDOM` model.
+            The function that will render a :ref:`VDOM <VDOM Mimetype>` model.
     """
     if not inspect.iscoroutinefunction(function):
         raise TypeError(f"Expected a coroutine function, not {function}")
@@ -49,7 +49,7 @@ def id(self) -> str:
 
     @abc.abstractmethod
     async def render(self) -> "VdomDict":
-        """Render the element's :term:`VDOM` model."""
+        """Render the element's :ref:`VDOM <VDOM Mimetype>` model."""
 
 
 class Element(AbstractElement):

idom/core/element.py

@@ -123,7 +123,9 @@ def constructor(
     constructor.__name__ = tag
     qualname_prefix = constructor.__qualname__.rsplit(".", 1)[0]
     constructor.__qualname__ = qualname_prefix + f".{tag}"
-    constructor.__doc__ = f"""Create a new ``<{tag}/>`` - returns :term:`VDOM`."""
+    constructor.__doc__ = (
+        f"""Create a new ``<{tag}/>`` - returns :ref:`VDOM <VDOM Mimetype>`."""
+    )
 
     return constructor