doc updates

Author: rmorshea

docs/source/_exts/build_custom_js.py

@@ -9,4 +9,5 @@
 
 
 def setup(app: Sphinx) -> None:
-    subprocess.run(["npm", "run", "build"], cwd=CUSTOM_JS_DIR, shell=True)
+    subprocess.run("npm install", cwd=CUSTOM_JS_DIR, shell=True)
+    subprocess.run("npm run build", cwd=CUSTOM_JS_DIR, shell=True)

docs/source/custom_js/package-lock.json

@@ -17,30 +17,53 @@ This can be accomplished in different ways for different reasons:
     *   - Integration Method
         - Use Case
 
+    *   - :ref:`Dynamically Loaded Components`
+        - You want to **quickly experiment** with IDOM and the Javascript ecosystem.
+
     *   - :ref:`Custom Javascript Components`
         - You want to create polished software that can be **easily shared** with others.
 
-    *   - :ref:`Dynamically Install Javascript` (requires NPM_)
-        - You want to **quickly experiment** with IDOM and the Javascript ecosystem.
+
+Dynamically Loaded Components
+-----------------------------
+
+.. note::
+
+    This method is not recommended in production systems - see
+    :ref:`Distributing Javascript Components` for more info.
+
+IDOM makes it easy to draft your code when you're in the early stages of development by
+using a CDN_ to dynamically load Javascript packages on the fly. In this example we'll
+be using the ubiquitous React-based UI framework `Material UI`_.
+
+.. example:: material_ui_button_no_action
+
+So now that we can display a Material UI Button we probably want to make it do
+something. Thankfully there's nothing new to learn here, you can pass event handlers to
+the button just as you did when :ref:`getting started`. Thus, all we need to do is add
+an ``onClick`` handler to the component:
+
+.. example:: material_ui_button_on_click
 
 
 Custom Javascript Components
 ----------------------------
 
-For projects that will be shared with others we recommend bundling your Javascript with
+For projects that will be shared with others, we recommend bundling your Javascript with
 `rollup <https://rollupjs.org/guide/en/>`__ or `webpack <https://webpack.js.org/>`__
 into a
 `web module <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules>`__.
 IDOM also provides a
 `template repository <https://github.com/idom-team/idom-react-component-cookiecutter>`__
 that can be used as a blueprint to build a library of React components.
 
-The core benefit of loading Javascript in this way is that users of your code won't need
-to have NPM_ installed. Rather, they can use ``pip`` to install your Python package
-without any other build steps because the bundled Javascript you distributed with it
-will be symlinked into the IDOM client at runtime.
+To work as intended, the Javascript bundle must provide named exports for the following
+functions as well as any components that will be rendered.
+
+.. note::
 
-To work as intended, the Javascript bundle must export the following named functions:
+    The exported components do not have to be React-based since you'll have full control
+    over the rendering mechanism.
 
 .. code-block:: typescript
 
@@ -63,25 +86,17 @@ These functions can be thought of as being analogous to those from React.
 .. |reactDOM.unmountComponentAtNode| replace:: ``reactDOM.unmountComponentAtNode``
 .. _reactDOM.unmountComponentAtNode: https://reactjs.org/docs/react-api.html#createelement
 
-And will be called in the following manner:
+And will be called in the following manner, where ``component`` is a named export of
+your module:
 
 .. code-block::
 
     // on every render
-    renderElement(createElement(type, props), container);
+    renderElement(createElement(component, props), container);
     // on unmount
     unmountElement(container);
 
-Once you've done this, you can distribute the bundled javascript in your Python package
-and integrate it into IDOM by defining :class:`~idom.client.module.Module` objects that
-load them from source:
-
-.. code-block::
-
-    import idom
-    my_js_package = idom.Module("my-js-package", source_file="/path/to/my/bundle.js")
-
-The simplest way to try this out yourself though, is to hook in simple a hand-crafted
+The simplest way to try this out yourself though, is to hook in a simple hand-crafted
 Javascript module that has the requisite interface. In the example to follow we'll
 create a very basic SVG line chart. The catch though is that we are limited to using
 Javascript that can run directly in the browser. This means we can't use fancy syntax
@@ -91,58 +106,40 @@ like `JSX <https://reactjs.org/docs/introducing-jsx.html>`__ and instead will us
 .. example:: super_simple_chart
 
 
-.. Links
-.. =====
+Distributing Javascript Components
+----------------------------------
 
-.. _Material UI: https://material-ui.com/
-.. _NPM: https://www.npmjs.com
-.. _install NPM: https://www.npmjs.com/get-npm
-
-
-
-Dynamically Install Javascript
-------------------------------
-
-.. warning::
-
-    - Before continuing `install NPM`_.
-    - Not guaranteed to work in all client implementations
-      (see :attr:`~idom.config.IDOM_CLIENT_MODULES_MUST_HAVE_MOUNT`)
-
-IDOM makes it easy to draft your code when you're in the early stages of development by
-using NPM_ to directly install Javascript packages on the fly. In this example we'll be
-using the ubiquitous React-based UI framework `Material UI`_ which can be installed
-using the ``idom`` CLI:
-
-.. code-block:: bash
-
-    idom install @material-ui/core
+There are two ways that you can distribute your :ref:`Custom Javascript Components`:
 
-Or at runtime with :func:`idom.client.module.install` (this is useful if you're working
-in a REPL or Jupyter Notebook):
+- In a Python package via PyPI_
+- Using a CDN_
 
-.. code-block::
-
-    import idom
-    material_ui = idom.install("@material-ui/core")
-    # or install multiple modules at once
-    material_ui, *other_modules = idom.install(["@material-ui/core", ...])
-
-.. note::
+That can be subsequently loaded using the respective functions:
 
-    Any standard javascript dependency specifier is allowed here.
+- :func:`~idom.web.module.module_from_file`
+- :func:`~idom.web.module.module_from_url`
 
-Once the package has been successfully installed, you can import and display the component:
+These options are not mutually exclusive though - if you upload your Javascript
+components to NPM_ and also bundle your Javascript inside a Python package, in principle
+your users can determine which option work best for them. Regardless though, either you
+or, if you give then the choice, your users, will have to consider the tradeoffs of
+either approach.
 
-.. example:: material_ui_button_no_action
+- Distribution via PyPI_ - This method is ideal for local usage since the user can
+  server all the Javascript components they depend on from their computer without
+  requiring a network connection.
 
+- Distribution via a CDN_ - Most useful in production-grade applications where its assumed
+  the user has a network connection. In this scenario a CDN's
+  `edge network <https://en.wikipedia.org/wiki/Edge_computing>`__ can be used to bring
+  the Javascript source closer to the user in order to reduce page load times.
 
-Passing Props To Javascript Components
---------------------------------------
 
-So now that we can install and display a Material UI Button we probably want to make it
-do something. Thankfully there's nothing new to learn here, you can pass event handlers
-to the button just as you did when :ref:`getting started`. Thus, all we need to do is
-add an ``onClick`` handler to the component:
+.. Links
+.. =====
 
-.. example:: material_ui_button_on_click
+.. _Material UI: https://material-ui.com/
+.. _NPM: https://www.npmjs.com
+.. _install NPM: https://www.npmjs.com/get-npm
+.. _CDN: https://en.wikipedia.org/wiki/Content_delivery_network
+.. _PyPI: https://pypi.org/

docs/source/javascript-components.rst

@@ -62,7 +62,7 @@ def docs(session: Session) -> None:
         # for some reason this matches absolute paths
         "--ignore=**/auto/*",
         "--ignore=**/_static/custom.js",
-        "--ignore=**/node_modules/**/*",
+        "--ignore=**/node_modules/*",
         "--ignore=**/package-lock.json",
         "-a",
         "-E",

noxfile.py

@@ -27,7 +27,7 @@
 """A named souce - usually a Javascript package name"""
 
 URL_SOURCE = SourceType("URL")
-"""A source loaded from a URL, usually from a CDN"""
+"""A source loaded from a URL, usually a CDN"""
 
 
 def module_from_url(
@@ -36,6 +36,19 @@ def module_from_url(
     resolve_exports: bool = IDOM_DEBUG_MODE.current,
     resolve_exports_depth: int = 5,
 ) -> WebModule:
+    """Load a :class:`WebModule` from a :data:`URL_SOURCE`
+
+    Parameters:
+        url:
+            Where the javascript module will be loaded from which conforms to the
+            interface for :ref:`Custom Javascript Components`
+        fallback:
+            What to temporarilly display while the module is being loaded.
+        resolve_imports:
+            Whether to try and find all the named exports of this module.
+        resolve_exports_depth:
+            How deeply to search for those exports.
+    """
     return WebModule(
         source=url,
         source_type=URL_SOURCE,
@@ -51,33 +64,50 @@ def module_from_url(
 
 def module_from_template(
     template: str,
-    name: str,
+    package: str,
     cdn: str = "https://esm.sh",
     fallback: Optional[Any] = None,
     resolve_exports: bool = IDOM_DEBUG_MODE.current,
     resolve_exports_depth: int = 5,
 ) -> WebModule:
+    """Load a :class:`WebModule` from a :data:`URL_SOURCE` using a known framework
+
+    Parameters:
+        template:
+            The name of the template to use with the given ``package`` (``react`` | ``preact``)
+        package:
+            The name of a package to load. May include a file extension (defaults to
+            ``.js`` if not given)
+        cdn:
+            Where the package should be loaded from. The CDN must distribute ESM modules
+        fallback:
+            What to temporarilly display while the module is being loaded.
+        resolve_imports:
+            Whether to try and find all the named exports of this module.
+        resolve_exports_depth:
+            How deeply to search for those exports.
+    """
     cdn = cdn.rstrip("/")
 
-    template_file_name = f"{template}{module_name_suffix(name)}"
+    template_file_name = f"{template}{module_name_suffix(package)}"
     template_file = Path(__file__).parent / "templates" / template_file_name
     if not template_file.exists():
         raise ValueError(f"No template for {template_file_name!r} exists")
 
-    target_file = _web_module_path(name)
+    target_file = _web_module_path(package)
     if not target_file.exists():
         target_file.parent.mkdir(parents=True, exist_ok=True)
         target_file.write_text(
-            template_file.read_text().replace("$PACKAGE", name).replace("$CDN", cdn)
+            template_file.read_text().replace("$PACKAGE", package).replace("$CDN", cdn)
         )
 
     return WebModule(
-        source=name + module_name_suffix(name),
+        source=package + module_name_suffix(package),
         source_type=NAME_SOURCE,
         default_fallback=fallback,
         file=target_file,
         export_names=(
-            resolve_module_exports_from_url(f"{cdn}/{name}", resolve_exports_depth)
+            resolve_module_exports_from_url(f"{cdn}/{package}", resolve_exports_depth)
             if resolve_exports
             else None
         ),
@@ -92,6 +122,23 @@ def module_from_file(
     resolve_exports_depth: int = 5,
     symlink: bool = False,
 ) -> WebModule:
+    """Load a :class:`WebModule` from a :data:`URL_SOURCE` using a known framework
+
+    Parameters:
+        template:
+            The name of the template to use with the given ``package``
+        package:
+            The name of a package to load. May include a file extension (defaults to
+            ``.js`` if not given)
+        cdn:
+            Where the package should be loaded from. The CDN must distribute ESM modules
+        fallback:
+            What to temporarilly display while the module is being loaded.
+        resolve_imports:
+            Whether to try and find all the named exports of this module.
+        resolve_exports_depth:
+            How deeply to search for those exports.
+    """
     source_file = Path(file)
     target_file = _web_module_path(name)
     if not source_file.exists():