Merge pull request #3099 from willingc/update-rm

Refactor outdated README

Author: willingc

README.md

@@ -1,13 +1,15 @@
 # ipywidgets: Interactive HTML Widgets
 
-[![Version](https://img.shields.io/pypi/v/ipywidgets.svg)](https://pypi.python.org/pypi/ipywidgets)
-![Build Status](https://img.shields.io/github/workflow/status/jupyter-widgets/ipywidgets/Test/master)
-[![Documentation Status](http://readthedocs.org/projects/ipywidgets/badge/?version=stable)](https://ipywidgets.readthedocs.io/)
-[![Join the chat at https://gitter.im/ipython/ipywidgets](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/jupyter-widgets/Lobby)
-[![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/jupyter-widgets/ipywidgets/master?filepath=docs%2Fsource%2Fexamples)
+|    Purpose                        |     Badges                       |
+|----------------------------|----------------------------|
+| **Latest (master: future 8.0)**  | [![Build Status](https://travis-ci.org/jupyter-widgets/ipywidgets.svg?branch=master)](https://travis-ci.org/jupyter-widgets/ipywidgets) [![Documentation Status: latest](https://img.shields.io/readthedocs/ipywidgets?logo=read-the-docs)](https://ipywidgets.readthedocs.io/en/latest/?badge=latest) [![Binder:master](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/jupyter-widgets/ipywidgets/master?filepath=docs%2Fsource%2Fexamples) |
+| **Stable (7.6.3)** | [![Version](https://img.shields.io/pypi/v/ipywidgets.svg?logo=pypi)](https://pypi.python.org/pypi/ipywidgets) [![Conda Version](https://img.shields.io/conda/vn/conda-forge/ipywidgets.svg?logo=conda-forge)](https://anaconda.org/conda-forge/ipywidgets) [![Documentation Status: 7.6.3](https://img.shields.io/readthedocs/ipywidgets?logo=read-the-docs)](https://ipywidgets.readthedocs.io/en/7.6.3/?badge=7.6.3) [![Binder:7.x](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/jupyter-widgets/ipywidgets/7.x?filepath=docs%2Fsource%2Fexamples) |
+| **Communication** | [![Join the chat at https://gitter.im/ipython/ipywidgets](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/jupyter-widgets/Lobby) [![Discourse](https://img.shields.io/badge/help_forum-discourse-blue?logo=discourse)](https://discourse.jupyter.org/) |
+| | |
 
-ipywidgets are [interactive HTML widgets](https://github.com/jupyter-widgets/ipywidgets/blob/master/docs/source/examples/Index.ipynb)
-for Jupyter notebooks, JupyterLab and the IPython kernel.
+**ipywidgets**, also known as jupyter-widgets or simply widgets, are
+[interactive HTML widgets](https://github.com/jupyter-widgets/ipywidgets/blob/master/docs/source/examples/Index.ipynb)
+for Jupyter notebooks and the IPython kernel.
 
 Notebooks come alive when interactive widgets are used. Users gain control of
 their data and can visualize changes in the data.
@@ -18,7 +20,9 @@ ipywidgets to your notebooks, and we're here to help you get started.
 
 ## Core Interactive Widgets
 
-A [demonstration notebook](https://github.com/jupyter-widgets/ipywidgets/blob/master/docs/source/examples/Index.ipynb) provides an overview of the core interactive widgets, including:
+The fundamental widgets provided by this library are called core interactive
+widgets. A [demonstration notebook](https://github.com/jupyter-widgets/ipywidgets/blob/master/docs/source/examples/Index.ipynb)
+provides an overview of the core interactive widgets, including:
 
 - sliders
 - progress bars
@@ -30,91 +34,104 @@ A [demonstration notebook](https://github.com/jupyter-widgets/ipywidgets/blob/ma
 ## Jupyter Interactive Widgets as a Framework
 
 Besides the widgets already provided with the library, the framework can be
-extended with custom widget libraries.
+extended with the development of **custom widget libraries**. For detailed
+information, please refer to the [ipywidgets documentation](https://ipywidgets.readthedocs.io/en/latest/).
 
-A template project is available in the form of a cookie cutter [here](https://github.com/jupyter-widgets/widget-ts-cookiecutter).
+### Cookiecutter template for custom widget development
 
-This project is meant to help custom widget authors get started with the
-packaging and the distribution of Jupyter interactive widgets.
-
-It produces a project for a Jupyter interactive widget library following the
-current best practices for using interactive widgets. An implementation for a
-placeholder "Hello World" widget is provided.
+A template project for building custom widgets is available as a
+[**cookiecutter**](https://github.com/jupyter-widgets/widget-ts-cookiecutter).
+This cookiecutter project helps custom widget authors get started with the
+packaging and the distribution of their custom Jupyter interactive widgets.
+The cookiecutter produces a project for a Jupyter interactive widget library
+following the current best practices for using interactive widgets. An
+implementation for a placeholder "Hello World" widget is provided as an example.
 
 Popular widget libraries such as
-[bqplot](https://github.com/bloomberg/bqplot),
-[pythreejs](https://github.com/jovyan/pythreejs) and
-[ipyleaflet](https://github.com/ellisonbg/ipyleaflet)
-
-follow exactly the same template and directory structure. They can serve as
+[bqplot](https://github.com/bqplot/bqplot),
+[pythreejs](https://github.com/jupyter-widgets/pythreejs) and
+[ipyleaflet](https://github.com/jupyter-widgets/ipyleaflet)
+follow exactly the same template and directory structure. They serve as
 more advanced examples of usage of the Jupyter widget infrastructure.
 
-For detailed information, please refer to the [ipywidgets documentation](https://ipywidgets.readthedocs.io/en/latest/).
-
-## More advanced examples
+### Popular custom widget examples
 
 Examples of custom widget libraries built upon ipywidgets are
 
-- [bqplot](https://github.com/bloomberg/bqplot) a 2d data visualization library
+- [bqplot](https://github.com/bqplot/bqplot) a 2d data visualization library
   enabling custom user interactions.
-- [pythreejs](https://github.com/jovyan/pythreejs) a Jupyter - Three.js wrapper,
+- [pythreejs](https://github.com/jupyter-widgets/pythreejs) a Jupyter - Three.js wrapper,
   bringing Three.js to the notebook.
-- [ipyleaflet](https://github.com/ellisonbg/ipyleaflet) a leaflet widget for Jupyter.
+- [ipyleaflet](https://github.com/jupyter-widgets/ipyleaflet) a leaflet widget for Jupyter.
 
 ## Install
 
-Install the current version of ipywidgets using pip or conda.
+The stable version of ipywidgets can be installed with [pip](#with-pip) or [conda](#with-conda).
+If using JupyterLab, review the [Front-end extension for JupyterLab](#front-end-extension-for-jupyterlab) section.
 
-- With pip:
+### With pip
 
-```
+```sh
 pip install ipywidgets
-jupyter nbextension enable --py --sys-prefix widgetsnbextension  # can be skipped for notebook version 5.3 and above
+# Skip the next step if using JupyterLab or Classic notebook version 5.3 and above
+jupyter nbextension enable --py --sys-prefix widgetsnbextension
 ```
 
-- With conda:
+### With conda
 
-```
+```sh
 conda install -c conda-forge ipywidgets
 ```
 
-- Install the front-end extension to JupyterLab (note that this requires nodejs to be installed):
+### Front-end extension for JupyterLab
 
-   * For JupyterLab 1.0.x and 1.1.x, use `jupyter labextension install @jupyter-widgets/[email protected]`
-   * For JupyterLab 1.2.x, use `jupyter labextension install @jupyter-widgets/[email protected]`
-   * For JupyterLab 2.x, use `jupyter labextension install @jupyter-widgets/[email protected]`
+Install the front-end extension to JupyterLab (note that this requires nodejs
+to be installed):
 
-   See the [Installation](docs/source/user_install.md) section of the documentation for additional details.
+- For JupyterLab 1.0.x and 1.1.x, use `jupyter labextension install @jupyter-widgets/[email protected]`
+- For JupyterLab 1.2.x, use `jupyter labextension install @jupyter-widgets/[email protected]`
+- For JupyterLab 2.x, use `jupyter labextension install @jupyter-widgets/[email protected]`
 
-### Installing from git
+See the [Installation](docs/source/user_install.md) section of the documentation
+for additional details.
 
-If you want to install ipywidgets from git, **you will need the
-[yarn](https://yarnpkg.com/) package manager version 1.2.1 or later**.
-Installing from git is more complicated and requires a developer install, see the [developer install](docs/source/dev_install.md) instructions.
+### Developer install from source
+
+Installing from source is more complicated and requires a developer install,
+see the detailed [developer install](docs/source/dev_install.md) instructions.
 
+If you want to install ipywidgets from source, **you will need the
+[yarn](https://yarnpkg.com/) package manager version 1.2.1 or later**.
 To install the latest master version from the root directory of the source
-code, run ``dev-install.sh``. To only build the Python package enter ``pip install -e .``.
+code, run ``dev-install.sh``. To only build the Python package enter
+``pip install -e .``.
+
+## Usage
 
-#### Compatibility
+See the [examples](docs/source/examples.md) section of the documentation. The widgets are being used in a variety of ways; some uses can be seen in these notebooks:
+[Demo notebook of interactive widgets](https://github.com/jupyter-widgets/ipywidgets/blob/master/docs/source/examples/Index.ipynb)
 
-| ipywidgets version  | Required notebook version |
-| ------------------- | ------------------------- |
-| master              | 4.4                       |
-| 5.x                 | 4.2                       |
-| 4.1.x               | 4.1                       |
-| 4.0.x               | 4.0                       |
+## Change log
 
 [Change log](docs/source/changelog.md)
 
-## Usage
+### Version Compatibility with Front-End Clients
 
-See the [examples](docs/source/examples.md) section of the documentation. The widgets are being used in a variety of ways; some uses can be seen in these notebooks:
+Refer to change log for more detail.
 
-- [Demo notebook of interactive widgets](https://github.com/jupyter-widgets/ipywidgets/blob/master/docs/source/examples/Index.ipynb)
+| ipywidgets | JupyterLab       | [Classic Notebook](https://github.com/jupyter/notebook) | [nbclassic](https://github.com/jupyterlab/nbclassic) |
+| ---------- | :--------------: | :--------------: | :---------: |
+| master     |                  |         -        | TBD   |
+| 7.6.3      |                  |                  | 0.2.6 |
+| **Legacy** |                  |                  |   |
+| 6.x        |                  |                  | - |
+| 5.x        |                  | 4.2              | - |
+| 4.1.x      |                  | 4.1              | - |
+| 4.0.x      |                  | 4.0              | - |
 
 ## Contributing to ipywidgets
 
-- [Developer information](CONTRIBUTING.md)
+[Developer information](CONTRIBUTING.md)
 
 ## License
 
@@ -126,6 +143,7 @@ See the [LICENSE](LICENSE) file in this repository for details.
 ## Project Jupyter resources
 
 - [Project Jupyter website](https://jupyter.org)
-- [Online Demo of Jupyter Notebook at try.jupyter.org](https://try.jupyter.org)
+- [Online Demo at try.jupyter.org](https://try.jupyter.org)
 - [Documentation for Project Jupyter](https://jupyter.readthedocs.io/en/latest/index.html) [[PDF](https://media.readthedocs.org/pdf/jupyter/latest/jupyter.pdf)]
-- [![Google Group](https://img.shields.io/badge/-Google%20Group-lightgrey.svg)](https://groups.google.com/forum/#!forum/jupyter)
+- [![Discourse](https://img.shields.io/badge/help_forum-discourse-blue?logo=discourse)](https://discourse.jupyter.org/)
+  [![Google Group](https://img.shields.io/badge/-Google%20Group-lightgrey.svg)](https://groups.google.com/forum/#!forum/jupyter)