Update FileUpload migration/changelog docs

Move the compatibility code to the migration guide, and cross-link from changelog.

Author: vidartf

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

@@ -67,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:

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