Merge pull request #3539 from jasongrout/migrating

Update docs

Author: jasongrout

docs/Readme.md

@@ -5,7 +5,7 @@ To build the ipywidgets documentation:
 1. Install the development version of ipywidgets with the `dev-install.sh` script in the repo root directory.
 2. Install the Python packages for building documentation with either mamba or conda:
    ```sh
-   conda update --file docs/environment.yml 
+   conda env update --file docs/environment.yml 
    ```
 
    or with `pip`:

docs/source/changelog.md

@@ -7,6 +7,10 @@ This is a summary of changes in ipywidgets releases. For more detailed informati
 To see the full list of pull requests and issues, see the [8.0 milestone](https://github.com/jupyter-widgets/ipywidgets/milestone/30?closed=1) on GitHub, or the 
 [full list of changes since 7.x](https://github.com/jupyter-widgets/ipywidgets/compare/7.x...master).
 
+See the [user migration guide](./user_migration_guides.md) for suggestions about migrating your code that uses ipywidgets to 8.0.
+
+If you author a custom widget, please see the [migration guide](./migration_guides.md) for suggestions about migrating your widget to support ipywidgets 8.
+
 ### Users
 
 Here are some highlights of user-visible changes in ipywidgets 8.0.
@@ -63,13 +67,17 @@ VBox([d, s])
 
 The file upload widget has been overhauled to handle multiple files in a more useful format:
 
-- The `.value` attribute is now a list of dictionaries, rather than a dictionary mapping the uploaded name to the content. To retrieve the original form, use `{f["name"]: f.content.tobytes() for f in uploader.value}`.
+- The `.value` attribute is now a list of dictionaries, rather than a dictionary mapping the uploaded name to the content.
 - The contents of each uploaded file is a [memory view](https://docs.python.org/3/library/stdtypes.html#memory-views) in the `.content` key, e.g., `uploader.value[0].content`.
-- The `.data` attribute has been removed. To retrieve it, use `[f.content.tobytes() for f in uploader.value]`.
-- The `.metadata` attribute has been removed. To retrieve it, use `[{k: v for k, v in f.items() if k != "content"} for f in w.value]`.
+- The `.data` attribute has been removed.
+- The `.metadata` attribute has been removed.
+
+See the [user migration guide](./user_migration_guides.md#FileUpload) for details on how to migrate your code.
 
  ([#2767](https://github.com/jupyter-widgets/ipywidgets/pull/2767), [#2724](https://github.com/jupyter-widgets/ipywidgets/pull/2724), [#2666](https://github.com/jupyter-widgets/ipywidgets/pull/2666), [#2480](https://github.com/jupyter-widgets/ipywidgets/issues/2480))
 
+
+
 #### More styling options
 
 Many style and layout options have been added to core widgets:
@@ -117,7 +125,7 @@ We have made it easier to load widgets from content delivery networks.
 
 - The default CDN is changed from unpkg to jsDelivr ([#3121](https://github.com/jupyter-widgets/ipywidgets/pull/3121), [#1627](https://github.com/jupyter-widgets/ipywidgets/issues/1627))
 - You can use the `data-jupyter-widgets-cdn-only` attribute to load modules only from CDN ([#2792](https://github.com/jupyter-widgets/ipywidgets/pull/2792), [#2786](https://github.com/jupyter-widgets/ipywidgets/issues/2786))
-- We have updated the webpack public path settings so the HTMLManager and the Jupyter Notebook extensions pull assets from wherever they are loaded, rather than only from CDN. [#3464](https://github.com/jupyter-widgets/ipywidgets/pull/3464), [#3508](https://github.com/jupyter-widgets/ipywidgets/pull/3508)
+- We have updated the webpack public path settings so the HTMLManager and the Jupyter Notebook extensions pull assets from wherever they are loaded, rather than only from CDN. If you author a custom widget, we highly encourage you to apply similar changes to your widget by adapting the changes at https://github.com/jupyter-widgets/widget-cookiecutter/pull/103/files. [#3464](https://github.com/jupyter-widgets/ipywidgets/pull/3464), [#3508](https://github.com/jupyter-widgets/ipywidgets/pull/3508)
 
 
 #### Other changes

docs/source/examples/Layout Templates.ipynb

@@ -6,7 +6,7 @@
    "source": [
     "# Using Layout Templates\n",
     "\n",
-    "As we showed in [Layout and Styling of Jupyter widgets](Widget%20Styling.ipynb) multiple widgets can be arranged together using the flexible [GridBox](Widget%20Styling.ipynb#The-Grid-Layout) specification. However, use of the specification involves some understanding of CSS properties and may impose sharp learning curve. Here, we will describe layout templates built on top of `GridBox` that simplify creation of common widget layouts."
+    "As we showed in [Layout of Jupyter widgets](Widget%20Layout.ipynb), multiple widgets can be arranged together using the flexible [GridBox](Widget%20Styling.ipynb#The-Grid-Layout) specification. However, use of the specification involves some understanding of CSS properties and may impose sharp learning curve. Here, we will describe layout templates built on top of `GridBox` that simplify creation of common widget layouts."
    ]
   },
   {

docs/source/index.rst

@@ -100,11 +100,11 @@ some custom widget packages built on top of the Jupyter Widgets framework.
     examples/Widget List.ipynb
     examples/Output Widget.ipynb
     examples/Widget Events.ipynb
-    examples/Widget Layout.ipynb
     examples/Widget Styling.ipynb
+    examples/Widget Layout.ipynb
     examples/Layout Templates.ipynb
-    examples/Widget Custom.ipynb
     examples/Using Interact.ipynb
+    examples/Widget Custom.ipynb
     examples/Widget Low Level.ipynb
     examples/Widget Asynchronous.ipynb
     embedding.md

docs/source/migration_guides.md

@@ -27,6 +27,8 @@ than one that contains widgets that you instantiated with ipywidgets 7.x.
 For a summarized list of relevant changes, please consult the "Developers" section of the
 [changelog](./changelog).
 
+You may consider updating your widget by generating a new widget from the cookiecutter at https://github.com/jupyter-widgets/widget-cookiecutter and adapting the changes to your widget. The widget cookiecutter has been updated to use best practices in Python packaging and Jupyter Widget infrastructure.
+
 ### Updating setup.py
 
 Start by updating the dependency in your `setup.py` or `setup.cfg` to support 8.x.
@@ -68,6 +70,10 @@ The ``ManagerBase`` class has been split into an interface type `IWidgetManager`
 + "@jupyter-widgets/base-manager": "^1",
 ```
 
+### Updating the AMD module logic
+
+We highly encourage you to update your widget's logic around generating AMD modules for the CDN with changes similar to those at https://github.com/jupyter-widgets/widget-cookiecutter/pull/103/files. These changes allow your AMD module to be hosted anywhere, rather than hardcoding the `unpkg.com` CDN, and they remove the differences between the AMD module generated for the notebook extension and the AMD module generated for the CDN.
+
 ### Updating the client-side code
 
 #### Phosphor -> Lumino

docs/source/user_install.md

@@ -5,7 +5,7 @@ Users can install the current version of **ipywidgets** with
 [pip](https://pip.pypa.io/en/stable/) or
 [conda](https://conda.readthedocs.io/en/latest/).
 
-In most cases, installing the Python `ipywidgets` package will also automatically configure classic Jupyter Notebook and JupyterLab 3.0 to display ipywidgets. With pip, do:
+In most cases, installing the Python `ipywidgets` package will also automatically configure classic Jupyter Notebook and JupyterLab 3.x to display ipywidgets. With pip, do:
 
 ``` bash
 pip install ipywidgets
@@ -17,61 +17,52 @@ or with conda, do:
 conda install -c conda-forge ipywidgets
 ```
 
-Installing in classic Jupyter Notebook
---------------------------------------
-
-Most of the time, installing `ipywidgets` automatically configures Jupyter Notebook to use widgets. The `ipywidgets` package does this by depending on the `widgetsnbextension` package, which configures the classic Jupyter Notebook to display and use widgets. If you have an old version of Jupyter Notebook installed, you may need to manually enable the ipywidgets notebook extension with:
-
-```bash
-jupyter nbextension enable --py widgetsnbextension
-```
-
-When using [virtualenv](https://virtualenv.pypa.io/en/stable/) and working in
-an activated virtual environment, the ``--sys-prefix`` option may be required
-to enable the extension and keep the environment isolated (i.e.
-``jupyter nbextension enable --py widgetsnbextension --sys-prefix``).
+Installing in JupyterLab 3.x
+----------------------------
 
+Most of the time, installing `ipywidgets` automatically configures JupyterLab 3.x to use widgets. The `ipywidgets` package does this by depending on the `jupyterlab_widgets` package, which configures JupyterLab 3 to display and use widgets. 
 
-If your Jupyter Notebook and the IPython kernel are installed in different
+If JupyterLab and the IPython kernel are installed in different
 environments (for example, separate environments are providing different
 Python kernels), then the installation requires two steps:
 
-1. Install the `widgetsnbextension` package in the environment
-containing the Jupyter Notebook server.
+1. Install the `jupyterlab_widgets` package in the environment containing JupyterLab.
 2. Install `ipywidgets` in each kernel's environment that will use ipywidgets.
 
-For example, if using conda environments, with Jupyter Notebook installed on the 
-`base` environment and the kernel installed in an environment called `py36`,
+For example, if using conda environments, with JupyterLab installed on the 
+`base` environment and the kernel installed in an environment called `pyenv`,
 the commands are:
 
 ```bash
-conda install -n base -c conda-forge widgetsnbextension
-conda install -n py36 -c conda-forge ipywidgets
+conda install -n base -c conda-forge jupyterlab_widgets
+conda install -n pyenv -c conda-forge ipywidgets
 ```
 
-Installing in JupyterLab 3.0
-----------------------------
 
-Most of the time, installing `ipywidgets` automatically configures JupyterLab 3.0 to use widgets. The `ipywidgets` package does this by depending on the `jupyterlab_widgets` package, version 1.0, which configures JupyterLab 3 to display and use widgets. 
+Installing in classic Jupyter Notebook
+--------------------------------------
+
+Most of the time, installing `ipywidgets` automatically configures Jupyter Notebook to use widgets. The `ipywidgets` package does this by depending on the `widgetsnbextension` package, which configures the classic Jupyter Notebook to display and use widgets. 
 
-If your JupyterLab and the IPython kernel are installed in different
+If your Jupyter Notebook and the IPython kernel are installed in different
 environments (for example, separate environments are providing different
 Python kernels), then the installation requires two steps:
 
-1. Install the `jupyterlab_widgets` package (version 1.0 or later) in the environment
-containing JupyterLab.
+1. Install the `widgetsnbextension` package in the environment
+containing the Jupyter Notebook server.
 2. Install `ipywidgets` in each kernel's environment that will use ipywidgets.
 
-For example, if using conda environments, with JupyterLab installed on the 
-`base` environment and the kernel installed in an environment called `py36`,
+For example, if using conda environments, with Jupyter Notebook installed on the 
+`base` environment and the kernel installed in an environment called `pyenv`,
 the commands are:
 
 ```bash
-conda install -n base -c conda-forge jupyterlab_widgets
-conda install -n py36 -c conda-forge ipywidgets
+conda install -n base -c conda-forge widgetsnbextension
+conda install -n pyenv -c conda-forge ipywidgets
 ```
 
 
+
 Installing into JupyterLab 1 or 2
 ---------------------------------
 
@@ -103,6 +94,23 @@ running the `jupyter lab clean` command which will remove the staging and
 static directories from the lab directory. The location of the lab directory
 can be queried by executing the command `jupyter lab path` in your terminal.
 
+Installing into classic Jupyter Notebook 5.2 or earlier
+-------------------------------------------------------
+
+If you have an old version of Jupyter Notebook installed (version 5.2 or
+earlier), you may need to manually enable the ipywidgets notebook extension
+with:
+
+```bash
+jupyter nbextension enable --py widgetsnbextension
+```
+
+When using [virtualenv](https://virtualenv.pypa.io/en/stable/) and working in
+an activated virtual environment, the ``--sys-prefix`` option may be required
+to enable the extension and keep the environment isolated (i.e.
+``jupyter nbextension enable --py widgetsnbextension --sys-prefix``).
+
+
 Frequently Asked Questions
 --------------------------
 

docs/source/user_migration_guides.md

@@ -24,7 +24,11 @@ be a list of dicts containing the file information. The keys of these dicts are:
 
 Suggested migration: Rewrite all usage of `FileUpload` to use the new structure.
 If you need to support both 7.x and 8.x, you can e.g. write functions `get_file_buffer` and similar
-to wrap reads from the widget.
+to wrap reads from the widget:
+
+- For the `.value` attribute, to retrieve it in the original form, use `{f["name"]: f.content.tobytes() for f in uploader.value}`.
+- For the `.data` attribute, use `[f.content.tobytes() for f in uploader.value]`.
+- For the `.metadata` attribute, use `[{k: v for k, v in f.items() if k != "content"} for f in w.value]`.
 
 #### Tooltips
 
@@ -79,7 +83,7 @@ use the `overflow` trait instead.
 
 #### Embedded CDN
 
-Please note that the default CDN of ipywidgets have changed from unpkg to jsDelivr. If
+Please note that the default CDN of ipywidgets has changed from unpkg to jsDelivr. If
 you rely on the CDN being unpkg, this can be overridden by specifying the data
 attribute `data-jupyter-widgets-cdn` on the HTML manager script tag. See
 [embedding](./embedding) for details.