make misc corrections

Author: rmorshea

Diff for: docs/source/_exts/idom_example.py

@@ -149,7 +149,7 @@ def _get_file_options(file: Path) -> list[str]:
 def _interactive_widget(name, with_activate_button):
     return _interactive_widget_template.format(
         name=name,
-        activate_button_opt="" if with_activate_button else ":activate-result:",
+        activate_button_opt=":activate-button:" if with_activate_button else "",
     )
 
 

Diff for: docs/source/_exts/idom_view.py

@@ -19,7 +19,7 @@ class IteractiveWidget(SphinxDirective):
     _next_id = 0
 
     option_spec = {
-        "activate-result": directives.flag,
+        "activate-button": directives.flag,
         "margin": float,
     }
 
@@ -47,7 +47,7 @@ def run(self):
                             "{container_id}",
                             "{view_id}",
                             "{_IDOM_EXAMPLE_HOST}",
-                            {"false" if "activate-result" in self.options else "true"},
+                            {"true" if "activate-button" in self.options else "false"},
                         );
                     </script>
                 </div>

Diff for: docs/source/adding-interactivity/responding-to-events.rst

@@ -102,7 +102,7 @@ Not all event data is serialized. The most notable example of this is the lack o
 ``target`` key in the dictionary sent back to the handler. Instead, data which is not
 inherhently JSON serializable must be treated on a case-by-case basis. A simple case
 to demonstrate this is the ``currentTime`` attribute of ``audio`` and ``video``
-elements. Normally this would be accessible via ``event.target.currenTime``, but here
+elements. Normally this would be accessible via ``event.target.currentTime``, but here
 it's simply passed in under the key ``currentTime``:
 
 .. idom:: _examples/audio_player
@@ -135,11 +135,10 @@ Stop Event Propogation
 ......................
 
 Similarly to :ref:`preventing default behavior <Preventing Default Event Actions>`, you
-can use the :func:`~idom.core.events.event` decorator to forward declare whether or not
-you want events from a child element propogate up through the document to parent
-elements by setting ``stop_propagation``. In the example below we place a red ``div``
-inside a parent blue ``div``. When propogation is turned on, clicking the red element
-will cause the handler for the outer blue one to fire. Conversely, when it's off, only
-the handler for the red element will fire.
+can use the :func:`~idom.core.events.event` decorator to prevent events originating in a
+child element from propagating to parent elements by setting ``stop_propagation``. In
+the example below we place a red ``div`` inside a parent blue ``div``. When propogation
+is turned on, clicking the red element will cause the handler for the outer blue one to
+trigger. Conversely, when it's off, only the handler for the red element will trigger.
 
 .. idom:: _examples/stop_event_propagation

Diff for: docs/source/conf.py

@@ -31,10 +31,26 @@
 # -- Common External Links ---------------------------------------------------
 
 extlinks = {
-    "issue": ("https://github.com/idom-team/idom/issues/%s", "#"),
-    "pull": ("https://github.com/idom-team/idom/pull/%s", "#"),
-    "discussion": ("https://github.com/idom-team/idom/discussions/%s", "#"),
-    "commit": ("https://github.com/idom-team/idom/commit/%s", ""),
+    "issue": (
+        "https://github.com/idom-team/idom/issues/%s",
+        "#",
+    ),
+    "pull": (
+        "https://github.com/idom-team/idom/pull/%s",
+        "#",
+    ),
+    "discussion": (
+        "https://github.com/idom-team/idom/discussions/%s",
+        "#",
+    ),
+    "discussion-type": (
+        "https://github.com/idom-team/idom/discussions/categories/%s",
+        "",
+    ),
+    "commit": (
+        "https://github.com/idom-team/idom/commit/%s",
+        "",
+    ),
 }
 
 # -- General configuration ---------------------------------------------------

Diff for: docs/source/developing-idom/contributor-guide.rst

@@ -4,8 +4,7 @@ Contributor Guide
 .. note::
 
     If you have any questions during set up or development post on our
-    `discussion board <https://github.com/idom-team/idom/discussions>`__ and we'll
-    answer them.
+    :discussion-type:`discussion board <question>` and we'll answer them.
 
 This project uses the `GitHub Flow`_ (more detail :ref:`below <Making a Pull Request>`)
 for collaboration and consists primarily of Python code and Javascript code. A variety
@@ -124,7 +123,7 @@ If you modify any Javascript, you'll need to re-install IDOM:
 
     pip install -e .
 
-However you may also ``cd`` to the ``src/idom/client/app`` directory which contains a
+However you may also ``cd`` to the ``src/client`` directory which contains a
 ``package.json`` that you can use to run standard ``npm`` commands from.
 
 
@@ -363,12 +362,17 @@ Other Core Repositories
 IDOM depends on, or is used by several other core projects. For documentation on them
 you should refer to their respective documentation in the links below:
 
-- https://github.com/idom-team/idom-react-component-cookiecutter - A template repo for
-  making :ref:`Custom Javascript Components`.
-- https://github.com/idom-team/flake8-idom-hooks - Enforces the :ref:`Rules of Hooks`
-- https://github.com/idom-team/idom-jupyter - IDOM integration for Jupyter
-- https://github.com/idom-team/idom-dash - IDOM integration for Plotly Dash
-- https://github.com/idom-team/django-idom - IDOM integration for Django
+- `idom-react-component-cookiecutter
+  <https://github.com/idom-team/idom-react-component-cookiecutter>`__ - Template repo
+  for making :ref:`Custom Javascript Components`.
+- `flake8-idom-hooks <https://github.com/idom-team/flake8-idom-hooks>`__ - Enforces the
+  :ref:`Rules of Hooks`
+- `idom-jupyter <https://github.com/idom-team/idom-jupyter>`__ - IDOM integration for
+  Jupyter
+- `idom-dash <https://github.com/idom-team/idom-dash>`__ - IDOM integration for Plotly
+  Dash
+- `django-idom <https://github.com/idom-team/django-idom>`__ - IDOM integration for
+  Django
 
 .. Links
 .. =====

Diff for: docs/source/developing-idom/index.rst

@@ -49,6 +49,8 @@ you can help move this project and community forward!
         See the long term goals of the IDOM team
 
 
+.. _everyone can contribute:
+
 Everyone Can Contribute!
 ------------------------
 
@@ -61,6 +63,5 @@ who can:
 - Report bugs
 - Participate in general discussions
 
-Still aren't sure what you have to offer? Just
-`ask us <https://github.com/idom-team/idom/discussions>`__ and we'll help you make your
-first contribution.
+Still aren't sure what you have to offer? Just :discussion-type:`ask us <question>` and
+we'll help you make your first contribution.

Diff for: docs/source/getting-started/index.rst

@@ -28,10 +28,11 @@ Getting Started
             See the ways that IDOM can be run with servers or be embedded in existing
             applications.
 
-The fastest way to get started with IDOM is to try it out in a Juptyer Notebook. If you
-want to use a Notebook to work through the examples shown in this documentation, you'll
-want to replace calls to ``idom.run(App)`` with a line at the end of each cell that
-constructs the ``App()`` in question. If that doesn't make sense, the introductory
+The fastest way to get started with IDOM is to try it out in a `Juptyer Notebook
+<https://mybinder.org/v2/gh/idom-team/idom-jupyter/main?urlpath=lab/tree/notebooks/introduction.ipynb>`__.
+If you want to use a Notebook to work through the examples shown in this documentation,
+you'll need to replace calls to ``idom.run(App)`` with a line at the end of each cell
+that constructs the ``App()`` in question. If that doesn't make sense, the introductory
 notebook linked below will demonstrate how to do this:
 
 .. card::
@@ -71,8 +72,8 @@ If you get a ``RuntimeError`` similar to the following:
 
 Then be sure you installed ``"idom[stable]"`` and not just ``idom``.
 
-For anything else, report your issue in IDOM's
-`discussion forum <https://github.com/idom-team/idom/discussions/categories/help>`__.
+For anything else, report your issue in IDOM's :discussion-type:`discussion forum
+<problem>`.
 
 .. card::
     :link: installing-idom

Diff for: docs/source/getting-started/installing-idom.rst

@@ -8,15 +8,16 @@ The easiest way to ``pip`` install idom is to do so using the ``stable`` option:
     pip install "idom[stable]"
 
 This includes a set of default dependencies for one of the builtin web server
-implementation.
+implementation. If you want to install IDOM without these dependencies you may simply
+``pip install idom``.
 
 
 Installing Other Servers
 ------------------------
 
-If you want to install IDOM without these dependencies you may simply ``pip install
-idom`` or, alternatively, if you want a specific web server implementation you can
-select on of the other installation options below:
+IDOM includes built-in support for a variety web server implementations. To install the
+required dependencies for each you should substitute ``stable`` from the ``pip install``
+command above with one of the options below:
 
 - ``fastapi`` - https://fastapi.tiangolo.com
 - ``flask`` - https://palletsprojects.com/p/flask/
@@ -29,16 +30,17 @@ If you need to, you can install more than one option by separating them with com
 
     pip install idom[fastapi,flask,sanic,tornado]
 
-Once this is complete you should be able to :ref:`run IDOM applications <Running IDOM>`.
+Once this is complete you should be able to :ref:`run IDOM <Running IDOM>` with your
+:ref:`chosen server implementation <choosing a server implementation>`.
 
 
 Installing In Other Frameworks
 ------------------------------
 
 While IDOM can run in a variety of contexts, sometimes web frameworks require extra work
-in orer to integrate with them. In these cases, the IDOM team distributes bindings for
-these frameworks as separate Python packages. For documentation on how to install and
-use these, follow the links below:
+in order to integrate with them. In these cases, the IDOM team distributes bindings for
+various frameworks as separate Python packages. For documentation on how to install and
+run IDOM in the supported frameworks, follow the links below:
 
 .. raw:: html
 
@@ -69,3 +71,29 @@ use these, follow the links below:
         :link: https://github.com/idom-team/idom-dash
         :img-background: _static/logo-plotly.svg
         :class-card: card-logo-image
+
+
+Installing for Development
+--------------------------
+
+If you want to contribute to the development of IDOM or modify it, you'll want to
+install a development version of IDOM. This involves cloning the repository where IDOM's
+source is maintained, and setting up a :ref:`development environment`. From there you'll
+be able to modifying IDOM's source code and :ref:`run its tests <Running The Tests>` to
+ensure the modifications you've made are backwards compatible. If you want to add a new
+feature to IDOM you should write your own test that validates its behavior.
+
+If you have questions about how to modify IDOM or help with its development, be sure to
+`start a discussion
+<https://github.com/idom-team/idom/discussions/new?category=question>`__. The IDOM team
+are always excited to :ref:`welcome <everyone can contribute>` new contributions and
+contributors of all kinds
+
+.. card::
+    :link: /developing-idom/index
+    :link-type: doc
+
+    :octicon:`book` Read More
+    ^^^^^^^^^^^^^^^^^^^^^^^^^
+
+    Learn more about how to contribute to the development of IDOM.

Diff for: docs/source/getting-started/running-idom.rst

@@ -1,3 +1,10 @@
+.. card::
+    :class-card: adminition hint
+
+    If IDOM is installed in another framework will require :ref:`different run
+    instructions <Installing In Other Frameworks>`.
+
+
 Running IDOM
 ============
 

Diff for: docs/source/index.rst

@@ -1,11 +1,11 @@
-.. note::
+.. card::
 
     This documentation is still under construction 🚧. We welcome your `feedback
     <https://github.com/idom-team/idom/discussions>`__!
 
 
-IDOM
-====
+What is IDOM?
+=============
 
 .. toctree::
     :hidden:
@@ -119,10 +119,9 @@ Chapter 2 - :ref:`Creating Interfaces`
 
 IDOM is a Python package for making user interfaces (UI). These interfaces are built
 from small elements of functionality like buttons text and images. IDOM allows you to
-combine these elements into reusable, nestable :ref:`"components" <your first
-components>`. In the sections that follow you'll learn how these UI elements are created
-and organized into components. Then, you'll use this knowledge to create interfaces from
-raw data:
+combine these elements into reusable :ref:`"components" <your first components>`. In the
+sections that follow you'll learn how these UI elements are created and organized into
+components. Then, you'll use this knowledge to create interfaces from raw data:
 
 .. idom:: creating-interfaces/_examples/todo_list_with_keys
 

Diff for: docs/source/reference-material/faq.rst

@@ -1,8 +1,7 @@
 FAQ
 ===
 
-See our `Discussion Forum <https://github.com/idom-team/idom/discussions>`__ for more
-questions and answers.
+See our :discussion-type:`Discussion Forum <question>` for more questions and answers.
 
 
 Do UI components run client-side?

Diff for: noxfile.py

@@ -11,6 +11,7 @@
 
 
 ROOT = Path(__file__).parent
+SRC = ROOT / "src"
 POSARGS_PATTERN = re.compile(r"^(\w+)\[(.+)\]$")
 
 
@@ -34,7 +35,7 @@ def format(session: Session) -> None:
     session.run("isort", ".")
 
     # format client Javascript
-    session.chdir(ROOT / "src" / "client")
+    session.chdir(SRC / "client")
     session.run("npm", "run", "format", external=True)
 
     # format docs Javascript
@@ -113,22 +114,24 @@ def docs_in_docker(session: Session) -> None:
 @nox.session
 def test(session: Session) -> None:
     """Run the complete test suite"""
-    session.notify("test_suite", posargs=session.posargs)
+    session.notify("test_python", posargs=session.posargs)
     session.notify("test_types")
     session.notify("test_style")
     session.notify("test_docs")
+    session.notify("test_javascript")
 
 
 @nox.session
 def test_short(session: Session) -> None:
     """Run a shortened version of the test suite"""
-    session.notify("test_suite", posargs=session.posargs)
+    session.notify("test_python", posargs=session.posargs)
     session.notify("test_docs")
+    session.notify("test_javascript")
 
 
 @nox.session
 @apply_standard_pip_upgrades
-def test_suite(session: Session) -> None:
+def test_python(session: Session) -> None:
     """Run the Python-based test suite"""
     session.env["IDOM_DEBUG_MODE"] = "1"
     install_requirements_file(session, "test-env")
@@ -191,6 +194,15 @@ def test_docs(session: Session) -> None:
     session.run("sphinx-build", "-b", "doctest", "docs/source", "docs/build")
 
 
+@nox.session
+def test_javascript(session: Session) -> None:
+    """Run the Javascript-based test suite and ensure it bundles succesfully"""
+    session.chdir(SRC / "client")
+    session.run("npm", "install", external=True)
+    session.run("npm", "run", "test", external=True)
+    session.run("npm", "run", "build", external=True)
+
+
 @nox.session
 def tag(session: Session):
     """Create a new git tag"""
@@ -255,7 +267,7 @@ def update_version(session: Session) -> None:
 
 @nox.session
 def build_js(session: Session) -> None:
-    session.chdir(ROOT / "src" / "client")
+    session.chdir(SRC / "client")
     session.run("npm", "run", "build", external=True)