Update VitessceWidget docs

Author: keller-mark

docs/api_config.rst

@@ -19,6 +19,17 @@ vitessce.config
  :exclude-members: VitessceConfig, VitessceChainableConfig
  :member-order: bysource
 
+vitessce.widget
+***************
+
+.. autoclass:: vitessce.widget.VitessceWidget()
+ :members:
+ :private-members:
+ :exclude-members: close
+
+.. autoclass:: vitessce.widget.VitesscePlugin
+ :members:
+
 vitessce.constants
 ******************
 

docs/api_data.rst

@@ -19,13 +19,13 @@ vitessce.wrappers
  :members:
 
 vitessce.export
-*****************
+***************
 
 .. automodule:: vitessce.export
  :members:
 
 vitessce.data_utils
-*****************
+*******************
 
 .. automodule:: vitessce.data_utils.ome
  :members:

src/vitessce/config.py

@@ -1791,6 +1791,17 @@ def widget(self, **kwargs):
         :param int height: The height of the widget, in pixels. By default, 600.
         :param int port: The port to use when serving data objects on localhost. By default, 8000.
         :param bool proxy: Is this widget being served through a proxy, for example with a cloud notebook (e.g. Binder)?
+        :param str js_package_version: The version of the NPM package ('vitessce' if not js_dev_mode else '@vitessce/dev').
+        :param bool js_dev_mode: Should @vitessce/dev be used (typically for debugging purposes)? By default, False.
+        :param str custom_js_url: A URL to a JavaScript file to use (instead of 'vitessce' or '@vitessce/dev' NPM package).
+        :param list[VitesscePlugin] plugins: A list of subclasses of VitesscePlugin. Optional.
+        :param bool remount_on_uid_change: Passed to the remountOnUidChange prop of the <Vitessce/> React component. By default, True.
+        :param bool prefer_local: Should local data be preferred (only applies to `*_artifact` data objects)? By default, True.
+        :param int invoke_timeout: The timeout in milliseconds for invoking Python functions from JavaScript. By default, 300000.
+        :param bool invoke_batched: Should invocations (Zarr gets) be submitted in batch, or individually? By default, True.
+        :param bool page_mode: Whether to render the <Vitessce/> component in grid-mode or page-mode. By default, False.
+        :param str page_esm: The ES module string for the page component creation function. Optional.
+        :param bool prevent_scroll: Should mouseover in the Vitessce widget prevent disable the scrolling of the notebook? By default, True.
 
         :returns: The Jupyter widget.
         :rtype: VitessceWidget

src/vitessce/widget.py

@@ -597,8 +597,12 @@ class VitesscePlugin:
     """
     A class that represents a Vitessce widget plugin. Custom plugins can be created by subclassing this class.
     """
-    plugin_esm = DEFAULT_PLUGIN_ESM
-    commands = {}
+
+    #: The ES module string for the plugin.
+    plugin_esm = DEFAULT_PLUGIN_ESM # type: str
+
+    #: A dictionary mapping command name strings to functions. Functions should take two arguments (message, buffers) and return a tuple (response, buffers).
+    commands = {} # type: dict
 
     def on_config_change(self, new_config):
         """
@@ -614,19 +618,29 @@ def on_config_change(self, new_config):
 
 class VitessceWidget(anywidget.AnyWidget):
     """
-    A class to represent a Jupyter widget for Vitessce.
+    A class to represent a Jupyter widget for Vitessce. Not intended to be instantiated directly; instead, use ``VitessceConfig.widget``.
+
+    .. code-block:: python
+        :emphasize-lines: 4
+
+        from vitessce import VitessceConfig
+
+        vc = VitessceConfig.from_object(my_scanpy_object)
+        vw = vc.widget()
+        vw
     """
     _esm = ESM
 
     # Widget specific property.
     # Widget properties are defined as traitlets. Any property tagged with `sync=True`
     # is automatically synced to the frontend *any* time it changes in Python.
     # It is synced back to Python from the frontend *any* time the model is touched.
-    _config = Dict({}).tag(sync=True)
-    """dict: Dictionary representation of the Vitessce JSON configuration. Synced via traitlets upon interactions."""
+    
+    #: Dictionary representation of the Vitessce JSON configuration. Synced via traitlets upon interactions.
+    _config = Dict({}).tag(sync=True) # type: dict
 
-    config = None
-    """VitessceConfig: The VitessceConfig instance used to create this widget. Not synced upon interactions."""
+    #: The VitessceConfig instance used to create this widget. Not synced upon interactions.
+    config = None # type: vitessce.config.VitessceConfig
 
     height = Int(600).tag(sync=True)
     theme = Unicode('auto').tag(sync=True)
@@ -650,9 +664,10 @@ class VitessceWidget(anywidget.AnyWidget):
     store_urls = List(trait=Unicode(''), default_value=[]).tag(sync=True)
 
     def __init__(self, config, height=600, theme='auto', uid=None, port=None, proxy=False, js_package_version='3.6.12', js_dev_mode=False, custom_js_url='', plugins=None, remount_on_uid_change=True, prefer_local=True, invoke_timeout=300000, invoke_batched=True, page_mode=False, page_esm=None, prevent_scroll=True):
+        """ """
         """
-        Construct a new Vitessce widget.
-
+        Construct a new Vitessce widget. Not intended to be instantiated directly; instead, use ``VitessceConfig.widget``.
+        
         :param config: A view config instance.
         :type config: VitessceConfig
         :param str theme: The theme name, either "light" or "dark". By default, "auto", which selects light or dark based on operating system preferences.
@@ -671,14 +686,7 @@ def __init__(self, config, height=600, theme='auto', uid=None, port=None, proxy=
         :param str page_esm: The ES module string for the page component creation function. Optional.
         :param bool prevent_scroll: Should mouseover in the Vitessce widget prevent disable the scrolling of the notebook? By default, True.
 
-        .. code-block:: python
-            :emphasize-lines: 4
-
-            from vitessce import VitessceConfig, VitessceWidget
-
-            vc = VitessceConfig.from_object(my_scanpy_object)
-            vw = vc.widget()
-            vw
+        Note: these parameter docstrings need to be manually kept in sync with the VitessceConfig.widget docstring.
         """
 
         base_url, use_port, VitessceWidget.next_port = get_base_url_and_port(
@@ -817,7 +825,7 @@ def ipython_display(config, height=600, theme='auto', base_url=None, host_name=N
         "has_host_name": host_name is not None,
         "height": height,
         "theme": theme,
-        "config": config_dict,
+        "_config": config_dict,
         "store_urls": [],
     }