add back in docs + binder support

Author: rmorshea

.gitignore

@@ -1,5 +1,4 @@
 *.egg-info/
-.ipynb_checkpoints/
 dist/
 build/
 *.py[cod]
@@ -12,5 +11,12 @@ idom_jupyter/labextension/
 # OS X
 .DS_Store
 
-# PyEnv
+# Py Env
 .python-version
+
+# VSCode
+.vscode
+
+# Jupyter
+.ipynb_checkpoints/
+Untitled*.ipynb

README.md

@@ -1,30 +1,106 @@
-idom-jupyter
-===============================
+# idom-jupyter
 
-A client for IDOM implemented using Jupyter widgets
+A client for [IDOM](https://github.com/idom-team/idom) implemented using Jupyter widgets
 
-Installation
-------------
+## Try It Now!
+
+Check out a live example by clicking the badge below:
+
+<a href="https://mybinder.org/v2/gh/idom-team/idom-jupyter/main?filepath=notebooks%2Fintroduction.ipynb">
+    <img alt="Binder" height="25px" src="https://mybinder.org/badge_logo.svg" />
+</a>
+
+## Getting Started
+
+Before anything else, do one of the following:
+
+1. At the top of your notebook run
+
+   ```python
+   import idom_jupyter
+   ```
+
+2. Register `idom_jupyter` as a permanant IPython extension in [your config file](https://ipython.readthedocs.io/en/stable/config/intro.html#introduction-to-ipython-configuration):
+
+   ```python
+   c.InteractiveShellApp.extensions = [
+       'idom_jupyter'
+   ]
+   ```
+
+## Usage
+
+Once you're done [getting started](#getting-started), you can author and display IDOM
+layouts natively in your Jupyter Notebook:
+
+```python
+import idom
+
+@idom.element
+def ClickCount():
+    count, set_count = idom.hooks.use_state(0)
+    return idom.html.button(
+        {"onClick": lambda event: set_count(count + 1)},
+        [f"Click count: {count}"],
+    )
+
+ClickCount()
+```
+
+You can also turn an `idom` element constructor into one that returns an `ipywidget` with
+the `idom_juptyer.widgetize` function. This is useful if you wish to use IDOM in combination
+with other Jupyter Widgets as in the following example:
+
+```python
+ClickCountWidget = idom_jupyter.widgetize(ClickCount)
+ipywidgets.Box(
+    [
+        ClickCountWidget(),
+        ClickCountWidget(),
+    ]
+)
+```
+
+Alternatively just wrap an `idom` element instance in an `idom_jupyter.LayoutWidget`:
+
+```python
+ipywidgets.Box(
+    [
+        idom_jupyter.LayoutWidget(ClickCount()),
+        idom_jupyter.LayoutWidget(ClickCount()),
+    ]
+)
+```
+
+# Installation
 
 To install use pip:
 
-    $ pip install idom_jupyter
+```
+pip install idom_jupyter
+```
 
 For a development installation (requires [Node.js](https://nodejs.org) and [Yarn version 1](https://classic.yarnpkg.com/)),
 
-    $ git clone https://github.com/idom-team/idom-jupyter.git
-    $ cd idom-jupyter
-    $ pip install -e .
-    $ jupyter nbextension install --py --symlink --overwrite --sys-prefix idom_jupyter
-    $ jupyter nbextension enable --py --sys-prefix idom_jupyter
+```
+git clone https://github.com/idom-team/idom-jupyter.git
+cd idom-jupyter
+pip install -e . -r requirements.txt
+jupyter nbextension install --py --symlink --overwrite --sys-prefix idom_jupyter
+jupyter nbextension enable --py --sys-prefix idom_jupyter
+```
 
 When actively developing your extension for JupyterLab, run the command:
 
-    $ jupyter labextension develop --overwrite idom_jupyter
+```
+jupyter labextension develop --overwrite idom_jupyter
+```
 
 Then you need to rebuild the JS when you make a code change:
 
-    $ cd js
-    $ yarn run build
+```
+cd js
+yarn run build
+```
 
 You then need to refresh the JupyterLab page when your javascript changes.

RELEASE.md

@@ -1,22 +1,22 @@
-- To release a new version of idom_jupyter on PyPI:
+To release a new version of idom-client-jupyter on PyPI:
 
-Update _version.py (set release version, remove 'dev')
-git add the _version.py file and git commit
-`python setup.py sdist upload`
-`python setup.py bdist_wheel upload`
-`git tag -a X.X.X -m 'comment'`
-Update _version.py (add 'dev' and increment minor)
-git add and git commit
-git push
-git push --tags
+- Update `_version.py` (set release version, remove 'dev')
+- git add the `_version.py` file and git commit
+- ```
+  python setup.py sdist bdist_wheel
+  twine upload dist/*
+  git tag -a X.X.X -m 'comment'
+  git add and git commit
+  git push
+  git push --tags
+  ```
 
-- To release a new version of idom-client-jupyter on NPM:
+To release a new version of idom-client-jupyter on NPM:
 
-Update `js/package.json` with new npm package version
-
-```
-# clean out the `dist` and `node_modules` directories
-git clean -fdx
-npm install
-npm publish
-```
+- Update `js/package.json` with new npm package version
+- ```
+  # clean out the `dist` and `node_modules` directories
+  git clean -fdx
+  npm install
+  npm publish
+  ```

binder/postBuild

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -e
+
+npm install -g yarn
+
+pip install -e .
+
+jupyter serverextension enable --py idom_jupyter
+jupyter nbextension install --py --symlink --sys-prefix idom_jupyter
+jupyter nbextension enable --py --sys-prefix idom_jupyter
+# jupyter labextension install js

idom_jupyter/_version.py

@@ -1,5 +1,5 @@
 # Module version
-version_info = (0, 3, 1, "final", 0)
+version_info = (0, 4, 0, "final", 0)
 
 # Module version stage suffix map
 _specifier_ = {"alpha": "a", "beta": "b", "candidate": "rc", "final": ""}

idom_jupyter/widget.py

@@ -52,9 +52,9 @@ class LayoutWidget(widgets.DOMWidget):
     _model_module = Unicode("idom-client-jupyter").tag(sync=True)
 
     # Version of the front-end module containing widget view
-    _view_module_version = Unicode("^0.1.0").tag(sync=True)
+    _view_module_version = Unicode("^0.4.0").tag(sync=True)
     # Version of the front-end module containing widget model
-    _model_module_version = Unicode("^0.1.0").tag(sync=True)
+    _model_module_version = Unicode("^0.4.0").tag(sync=True)
 
     _jupyter_server_base_url = Unicode().tag(sync=True)
 

js/lib/widget.js

@@ -8,8 +8,8 @@ var IdomModel = widgets.DOMWidgetModel.extend({
     _view_name: "IdomView",
     _model_module: "idom-client-jupyter",
     _view_module: "idom-client-jupyter",
-    _model_module_version: "0.1.0",
-    _view_module_version: "0.1.0",
+    _model_module_version: "0.4.0",
+    _view_module_version: "0.4.0",
     _jupyter_server_base_url: null,
   }),
 });
@@ -67,8 +67,8 @@ var _HackyClientHandshakeModel = widgets.DOMWidgetModel.extend({
     _view_name: "_HackyClientHandshakeView",
     _model_module: "idom-client-jupyter",
     _view_module: "idom-client-jupyter",
-    _model_module_version: "0.1.0",
-    _view_module_version: "0.1.0",
+    _model_module_version: "0.4.0",
+    _view_module_version: "0.4.0",
   }),
 });
 

notebooks/introduction.ipynb

@@ -122,9 +122,9 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.0"
+   "version": "3.7.7-final"
   }
  },
  "nbformat": 4,
  "nbformat_minor": 4
-}
+}

requirements.txt

@@ -0,0 +1,6 @@
+black
+flake8
+pre-commit
+wheel
+twine
+jupyter_packaging

setup.py

@@ -16,65 +16,84 @@
 here = os.path.dirname(os.path.abspath(__file__))
 
 log.set_verbosity(log.DEBUG)
-log.info('setup.py entered')
-log.info('$PATH=%s' % os.environ['PATH'])
+log.info("setup.py entered")
+log.info("$PATH=%s" % os.environ["PATH"])
 
-name = 'idom_jupyter'
-LONG_DESCRIPTION = 'A client for IDOM implemented using Jupyter widgets'
+name = "idom_jupyter"
+LONG_DESCRIPTION = "A client for IDOM implemented using Jupyter widgets"
 
 # Get idom_jupyter version
-version = get_version(pjoin(name, '_version.py'))
+version = get_version(pjoin(name, "_version.py"))
 
-js_dir = pjoin(here, 'js')
+js_dir = pjoin(here, "js")
 
 # Representative files that should exist after a successful build
 jstargets = [
-    pjoin(js_dir, 'dist', 'index.js'),
+    pjoin(js_dir, "dist", "index.js"),
 ]
 
 data_files_spec = [
-    ('share/jupyter/nbextensions/idom-client-jupyter', 'idom_jupyter/nbextension', '*.*'),
-    ('share/jupyter/labextensions/idom-client-jupyter', 'idom_jupyter/labextension', "**"),
-    ("share/jupyter/labextensions/idom-client-jupyter", '.', "install.json"),
-    ('etc/jupyter/nbconfig/notebook.d', '.', 'idom-client-jupyter.json'),
-    ("etc/jupyter/nbconfig", "jupyter-config", "**/*.json"),
+    (
+        "share/jupyter/nbextensions/idom-client-jupyter",
+        "idom_jupyter/nbextension",
+        "*.*",
+    ),
+    (
+        "share/jupyter/labextensions/idom-client-jupyter",
+        "idom_jupyter/labextension",
+        "**",
+    ),
+    (
+        "share/jupyter/labextensions/idom-client-jupyter",
+        ".",
+        "install.json",
+    ),
+    (
+        "etc/jupyter/nbconfig/notebook.d",
+        ".",
+        "idom-client-jupyter.json",
+    ),
+    (
+        "etc/jupyter/nbconfig",
+        "jupyter-config",
+        "**/*.json",
+    ),
 ]
 
-cmdclass = create_cmdclass('jsdeps', data_files_spec=data_files_spec)
-cmdclass['jsdeps'] = combine_commands(
-    install_npm(js_dir, npm=['yarn'], build_cmd='build:prod'), ensure_targets(jstargets),
+cmdclass = create_cmdclass("jsdeps", data_files_spec=data_files_spec)
+cmdclass["jsdeps"] = combine_commands(
+    install_npm(js_dir, npm=["yarn"], build_cmd="build:prod"),
+    ensure_targets(jstargets),
 )
 
 setup_args = dict(
     name=name,
     version=version,
-    description='A client for IDOM implemented using Jupyter widgets',
+    description="A client for IDOM implemented using Jupyter widgets",
     long_description=LONG_DESCRIPTION,
     include_package_data=True,
-    install_requires=[
-        'ipywidgets>=7.6.0', "idom>=0.20.1"
-    ],
+    install_requires=["ipywidgets>=7.6.0", "idom>=0.20.1"],
     packages=find_packages(),
     zip_safe=False,
     cmdclass=cmdclass,
-    author='Ryan Morshead',
-    author_email='ryan.morshead@gmail.com',
-    url='https://github.com/idom-team/idom-jupyter',
+    author="Ryan Morshead",
+    author_email="ryan.morshead@gmail.com",
+    url="https://github.com/idom-team/idom-jupyter",
     keywords=[
-        'ipython',
-        'jupyter',
-        'widgets',
+        "ipython",
+        "jupyter",
+        "widgets",
     ],
     classifiers=[
-        'Development Status :: 4 - Beta',
-        'Framework :: IPython',
-        'Intended Audience :: Developers',
-        'Intended Audience :: Science/Research',
-        'Topic :: Multimedia :: Graphics',
-        'Programming Language :: Python :: 3.6',
-        'Programming Language :: Python :: 3.7',
-        'Programming Language :: Python :: 3.8',
-        'Programming Language :: Python :: 3.9',
+        "Development Status :: 4 - Beta",
+        "Framework :: IPython",
+        "Intended Audience :: Developers",
+        "Intended Audience :: Science/Research",
+        "Topic :: Multimedia :: Graphics",
+        "Programming Language :: Python :: 3.6",
+        "Programming Language :: Python :: 3.7",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
     ],
 )