Merge pull request #109 from ibdafna/deprecation-note

Add deprecation note

README.md

@@ -1,4 +1,9 @@
-# widget-cookiecutter
+# widget-cookiecutter (deprecated)
+
+## This cookitcutter template is now deprecated
+
+### We recommend [anywidget](https://github.com/manzt/anywidget) as an alternative for those who want to learn or quickly prototype widgets. For production uses, we recommend the [TypeScript cookiecutter](https://github.com/jupyter-widgets/widget-ts-cookiecutter)
+
 #### A cookiecutter template for creating a custom Jupyter widget project
 
 [![Documentation Status](https://readthedocs.org/projects/ipywidgets/badge/?version=latest)](https://ipywidgets.readthedocs.io/en/latest/?badge=latest)
@@ -20,7 +25,7 @@ Popular widget libraries such as
 [bqplot](https://github.com/bloomberg/bqplot),
 [pythreejs](https://github.com/jovyan/pythreejs) and
 [ipyleaflet](https://github.com/ellisonbg/ipyleaflet)
- can serve as advanced examples of usage of the
+can serve as advanced examples of usage of the
 Jupyter widget infrastructure.
 
 ## Usage
@@ -54,6 +59,7 @@ your custom Jupyter widget.
 ## Files Generated by cookiecutter
 
 Jupyter widgets are composed of two separate programs:
+
 - A Python package for the code executed in notebook kernel as the backend of the widget
 - A Javascript package for the frontend of the widget running in browser
 
@@ -86,95 +92,107 @@ Running the cookiecutter generates the following file tree:
 ```
 
 - **`<python_package_name> directory`**\
-This directory contains the python package that runs in the kernel
+ This directory contains the python package that runs in the kernel
+
+ - **`__init__.py`**\
 
- - **`__init__.py`**\
-Marks the `<python_package_name>` directory as a python module, allowing `<python_package_name>` to be imported
+ Marks the `<python_package_name>` directory as a python module, allowing `<python_package_name>` to be imported
 
- - **`_version.py`**\
-Contains version definitions for both the backend and the frontend code, to be used from Python. You should not need to modify this file, apart from when you release a new version of the package.
+ - **`_version.py`**\
 
- - **`example.py`**\
-Example source file containing a widget. Modify this to define your own widgets.
+ Contains version definitions for both the backend and the frontend code, to be used from Python. You should not need to modify this file, apart from when you release a new version of the package.
+
+ - **`example.py`**\
+
+ Example source file containing a widget. Modify this to define your own widgets.
 
 - **`js directory`**\
-Source files for widget frontend. There are actually three different frontend programs:
+ Source files for widget frontend. There are actually three different frontend programs:
 
- 1. one that is suitable for loading the widget frontend in the classic notebook
- 2. one that is suitable for loading the widget frontend in standalone HTML webpages with no backend
- 3. one that is suitable for loading the widget frontend in JupyterLab
+  1. one that is suitable for loading the widget frontend in the classic notebook
+  2. one that is suitable for loading the widget frontend in standalone HTML webpages with no backend
+  3. one that is suitable for loading the widget frontend in JupyterLab
 
  Fortunately, you don't have to write three different versions of your widgets. There are three entrypoints that all load the widget source files. Each of the frontend program gets bundled using [webpack](https://webpack.js.org/):
 
- 1. The classic notebook frontend bundle gets created using `index.js` as the entrypoint.
- 2. The standalone frontend bundle gets created using `embed.js` as the entrypoint.
- 3. For JupyterLab, the frontend code gets folded into the JupyterLab frontend itself using JupyterLab's webpack. JupyterLab will include `labplugin.js` as the entrypoint to the widgets.
+ 1. The classic notebook frontend bundle gets created using `index.js` as the entrypoint.
+ 2. The standalone frontend bundle gets created using `embed.js` as the entrypoint.
+ 3. For JupyterLab, the frontend code gets folded into the JupyterLab frontend itself using JupyterLab's webpack. JupyterLab will include `labplugin.js` as the entrypoint to the widgets.
+
+ - **`lib directory`**\
+
+ Directory containing source files
+
+  - **`embed.js`**\
 
- - **`lib directory`**\
-Directory containing source files
+ Webpack entry-point for generating the code bundle that is loaded when widgets are used in a stand-alone HTML page. Learn more about embedding widgets into a stand-alone HTML page [here](https://ipywidgets.readthedocs.io/en/stable/embedding.html). When you add new source files to your project that declare widgets, you will need to export them here.
 
-  - **`embed.js`**\
-Webpack entry-point for generating the code bundle that is loaded when widgets are used in a stand-alone HTML page. Learn more about embedding widgets into a stand-alone HTML page [here](https://ipywidgets.readthedocs.io/en/stable/embedding.html). When you add new source files to your project that declare widgets, you will need to export them here.
+  - **`example.js`**\
 
-  - **`example.js`**\
-Widget frontend source code. Contains widget model and view class definitions. Widget model is derived from [DOMWidgetModel](https://github.com/jupyter-widgets/ipywidgets/blob/master/packages/base/src/widget.ts) which provides functionality to communicate with the model instance on kernel. Widget view is derived from [DOMWidgetView](https://github.com/jupyter-widgets/ipywidgets/blob/master/packages/base/src/widget.ts) which has a `model` attribute referencing to widget model it is presenting.
+ Widget frontend source code. Contains widget model and view class definitions. Widget model is derived from [DOMWidgetModel](https://github.com/jupyter-widgets/ipywidgets/blob/master/packages/base/src/widget.ts) which provides functionality to communicate with the model instance on kernel. Widget view is derived from [DOMWidgetView](https://github.com/jupyter-widgets/ipywidgets/blob/master/packages/base/src/widget.ts) which has a `model` attribute referencing to widget model it is presenting.
 
-  - **`extension.js`**\
-Entry-point that is loaded by the classic notebook to load your widget. You should not need to modify this. Note that this does not get included in the webpack bundle.
+  - **`extension.js`**\
 
-  - **`index.js`**\
-This is the entrypoint to your library. When you add new widgets, or change widget names, add these here. When bundling for the classic notebook, webpack will create a single bundle based on this file. This bundle is then loaded by `extension.js`. For JupyterLab, `labplugin.js` loads this file.
+ Entry-point that is loaded by the classic notebook to load your widget. You should not need to modify this. Note that this does not get included in the webpack bundle.
 
-  - **`labplugin.js`**\
-JupyterLab extension definition for JupyterLab integration. When JupyterLab loads, it activates the plugin defined in this file. Widget registry service provided by `@jupyter-widgets/jupyterlab-manager` is used during activation to register the widget with JupyterLab. You should not need to modify this file.
+  - **`index.js`**\
 
- - **`package.json`**\
-npm package definiton file for widget frontend. You should not need to modify this file, apart from to add new JavaScript dependencies.
+ This is the entrypoint to your library. When you add new widgets, or change widget names, add these here. When bundling for the classic notebook, webpack will create a single bundle based on this file. This bundle is then loaded by `extension.js`. For JupyterLab, `labplugin.js` loads this file.
 
- - **`README.md`**\
-Auto-generated documentation file for frontend npm package, with installation instructions.
+  - **`labplugin.js`**\
 
- - **`webpack.config.js`**\
-Webpack bundler configuration that defines bundler entry points and ouputs along with other configuration
+ JupyterLab extension definition for JupyterLab integration. When JupyterLab loads, it activates the plugin defined in this file. Widget registry service provided by `@jupyter-widgets/jupyterlab-manager` is used during activation to register the widget with JupyterLab. You should not need to modify this file.
+
+ - **`package.json`**\
+
+ npm package definiton file for widget frontend. You should not need to modify this file, apart from to add new JavaScript dependencies.
+
+ - **`README.md`**\
+
+ Auto-generated documentation file for frontend npm package, with installation instructions.
+
+ - **`webpack.config.js`**\
+
+ Webpack bundler configuration that defines bundler entry points and ouputs along with other configuration
 
 - **`.gitignore`**\
-Ignore rules for widget project git repository.
+ Ignore rules for widget project git repository.
 
 - **`<npm_package_name>.json`**\
-This file gets copied into the configuration directory for the classic notebook as part of the installation process. This enables the extension for the notebook. You should not need to modify this file.
+ This file gets copied into the configuration directory for the classic notebook as part of the installation process. This enables the extension for the notebook. You should not need to modify this file.
 
 - **`MANIFEST.in`**\
-setuptools configuration file containing commands to execute (include / exclude files) during installation (pip install). You should not need to modify this file, unless you change the directory structure for your project.
+ setuptools configuration file containing commands to execute (include / exclude files) during installation (pip install). You should not need to modify this file, unless you change the directory structure for your project.
 
 - **`README.md`**\
-Auto-generated documentation file for widget project.
+ Auto-generated documentation file for widget project.
 
 - **`RELEASE.md`**\
-Auto-generated documentation file with instructions for publishing python package to PyPI and npm package to npm registry.
+ Auto-generated documentation file with instructions for publishing python package to PyPI and npm package to npm registry.
 
 - **`setup.cfg`**\
-Configuration file to mark the python package as a [Universal Wheel](https://packaging.python.org/guides/distributing-packages-using-setuptools/#universal-wheels).
+ Configuration file to mark the python package as a [Universal Wheel](https://packaging.python.org/guides/distributing-packages-using-setuptools/#universal-wheels).
 
 - **`setup.py`**\
-Build script for the widget package. Note that the `setup.py` is heavily customised compared to pure Python packages. In particular, it builds the JavaScript code when creating a source distribution, and copies the notebook frontend into the right directory when a user installs the package.
+ Build script for the widget package. Note that the `setup.py` is heavily customised compared to pure Python packages. In particular, it builds the JavaScript code when creating a source distribution, and copies the notebook frontend into the right directory when a user installs the package.
 
 ## Local Dev Installation for Classic Notebook
 
 To develop this package against the classic notebook, run:
 
 - `pip install -e .` (installs python package for development, runs `npm install` and `npm run build`)
 - `jupyter nbextension install --py --symlink --sys-prefix <python_package_name>`\
-(symlinks `nbextension/` directory into `<jupyter path>/nbextensions/<extension_name>/`). Now the notebook has access to the frontend code.
+ (symlinks `nbextension/` directory into `<jupyter path>/nbextensions/<extension_name>/`). Now the notebook has access to the frontend code.
 - `jupyter nbextension enable --py --sys-prefix <python_package_name>`\
-(copies `<npm_package_name>.json` into  `<environment path>/etc/jupyter/nbconfig/notebook.d/` directory). Now the notebook will load your frontend code on page load.
+ (copies `<npm_package_name>.json` into `<environment path>/etc/jupyter/nbconfig/notebook.d/` directory). Now the notebook will load your frontend code on page load.
 
 Now make some changes to your source code. Then:
 
 - After making Python code changes, restarting the notebook kernel will be enough to reflect changes
 - After making JavaScript code changes:
-  - `cd js`
-  - `yarn run build`
-  - Refresh browser to reflect changes
+ - `cd js`
+ - `yarn run build`
+ - Refresh browser to reflect changes
 
 ## Local Dev Installation for JupyterLab
 
@@ -187,18 +205,22 @@ Now make some changes to your source code. Then:
 
 - After making Python code changes, restarting the notebook kernel will be enough to reflect changes
 - After making JavaScript code changes:
-  - `cd js`
-  - `yarn run build`
-  - Refresh browser to reflect changes
+ - `cd js`
+ - `yarn run build`
+ - Refresh browser to reflect changes
 
 ## Publishing Widget
+
 Follow the steps in (RELEASE.md) to publish widget python package and npm packages.
 
 ## Widget Installation Process for Notebook
+
 When installing published package in non-development mode
+
 - `pip install` installs python package for access from kernel and copies frontend code files from `nbextension/` directory into `<jupyter path>/nbextensions/<extension_name>/` and enables by copying `<npm_package_name>.json` file into `<environment path>/etc/jupyter/nbconfig/notebook.d/` directory.
 
 ## Widget Load Process for Notebook
+
 - Python code is loaded into kernel from python package directory
 - Frontend javascript code loaded from `<jupyter path>/nbextensions/<extension_name>/extension.js`