Skip to content

Commit

Permalink
Merge pull request #3099 from willingc/update-rm
Browse files Browse the repository at this point in the history 
Refactor outdated README
  • Loading branch information
@willingc
willingc authored Feb 7, 2021
2 parents ac456a5 + b162dca commit bd8ec45
Showing 1 changed file with 74 additions and 56 deletions.
130 changes: 74 additions & 56 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -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
Expand All @@ -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

Expand All @@ -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)

0 comments on commit bd8ec45

Please sign in to comment.