update docs + changelog + fix warning (#891)

Author: rmorshea

docs/source/_custom_js/package-lock.json

@@ -23,7 +23,46 @@ more info, see the :ref:`Contributor Guide <Creating a Changelog Entry>`.
 Unreleased
 ----------
 
-No changes.
+**Changed**
+
+- :pull:`841` - Revamped element constructor interface. Now instead of passing a
+  dictionary of attributes to element constructors, attributes are declared using
+  keyword arguments. For example, instead of writing:
+
+  .. code-block::
+
+      html.div({"className": "some-class"}, "some", "text")
+
+  You now should write:
+
+  .. code-block::
+
+      html.div("some", "text", class_name="some-class")
+
+  .. note::
+
+    All attributes are written using ``snake_case``.
+
+  In conjunction, with these changes, IDOM now supplies a command line utility that
+  makes a "best effort" attempt to automatically convert code to the new API. Usage of
+  this utility is as follows:
+
+  .. code-block:: bash
+
+      idom update-html-usages [PATHS]
+
+  Where ``[PATHS]`` is any number of directories or files that should be rewritten.
+
+  .. warning::
+
+    After running this utility, code comments and formatting may have been altered. It's
+    recommended that you run a code formatting tool like `Black
+    <https://github.com/psf/black>`__ and manually review and replace any comments that
+    may have been moved.
+
+**Fixed**
+
+- :issue:`755` - unification of component and VDOM constructor interfaces. See above.
 
 
 v0.44.0

docs/source/about/changelog.rst

@@ -71,7 +71,7 @@ Adding HTML Attributes
 ----------------------
 
 That's all well and good, but there's more to HTML than just text. What if we wanted to
-display an image? In HTMl we'd use the `<img/>` element and add attributes to it order
+display an image? In HTMl we'd use the ``<img>`` element and add attributes to it order
 to specify a URL to its ``src`` and use some ``style`` to modify and position it:
 
 .. code-block:: html
@@ -80,23 +80,27 @@ to specify a URL to its ``src`` and use some ``style`` to modify and position it
         src="https://picsum.photos/id/237/500/300"
         style="width: 50%; margin-left: 25%;"
         alt="Billie Holiday"
+        tabindex="0"
     />
 
-In IDOM we add these attributes to elements using dictionaries. There are some notable
-differences though. The biggest being the fact that all names in IDOM use ``camelCase``
-instead of dash-separated words. For example, ``margin-left`` becomes ``marginLeft``.
-Additionally, instead of specifying ``style`` using a string, we use a dictionary:
+In IDOM we add these attributes to elements using keyword arguments. There are two main
+notable differences though. First, all names in IDOM use ``snake_case`` instead of
+dash-separated words. For example, ``tabindex`` and ``margin-left`` become ``tab_index``
+and ``margin_left`` respectively. Second, instead of specifying ``style`` using a
+string, we use a dictionary. Given this, you can rewrite the ``<img>`` element above as:
 
 .. testcode::
 
     html.img(
         src="https://picsum.photos/id/237/500/300",
-        style={"width": "50%", "marginLeft": "25%"},
+        style={"width": "50%", "margin_left": "25%"},
         alt="Billie Holiday",
+        tab_index="0",
     )
 
 .. raw:: html
 
+    <!-- no tabindex since that would ruin accesibility of the page -->
     <img
         src="https://picsum.photos/id/237/500/300"
         style="width: 50%; margin-left: 25%;"

docs/source/guides/creating-interfaces/html-with-idom/index.rst

@@ -119,8 +119,16 @@ async def single_page_app_files(
     ) -> response.HTTPResponse:
         return response.html(index_html)
 
-    spa_blueprint.add_route(single_page_app_files, "/")
-    spa_blueprint.add_route(single_page_app_files, "/<_:path>")
+    spa_blueprint.add_route(
+        single_page_app_files,
+        "/",
+        name="single_page_app_files_root",
+    )
+    spa_blueprint.add_route(
+        single_page_app_files,
+        "/<_:path>",
+        name="single_page_app_files_path",
+    )
 
     async def asset_files(
         request: request.Request,
@@ -185,8 +193,16 @@ async def model_stream(
             recv,
         )
 
-    api_blueprint.add_websocket_route(model_stream, f"/{STREAM_PATH.name}")
-    api_blueprint.add_websocket_route(model_stream, f"/{STREAM_PATH.name}/<path:path>/")
+    api_blueprint.add_websocket_route(
+        model_stream,
+        f"/{STREAM_PATH.name}",
+        name="model_stream_root",
+    )
+    api_blueprint.add_websocket_route(
+        model_stream,
+        f"/{STREAM_PATH.name}/<path:path>/",
+        name="model_stream_path",
+    )
 
 
 def _make_send_recv_callbacks(