Improve the documentation for Notebook 7 (#6813)

* [pre-commit.ci] pre-commit autoupdate (#6814)

updates:
- [github.com/python-jsonschema/check-jsonschema: 0.21.0 → 0.22.0](python-jsonschema/check-jsonschema@0.21.0...0.22.0)
- [github.com/psf/black: 23.1.0 → 23.3.0](psf/black@23.1.0...23.3.0)
- [github.com/charliermarsh/ruff-pre-commit: v0.0.254 → v0.0.260](astral-sh/ruff-pre-commit@v0.0.254...v0.0.260)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

* Add note and warning on the extension landing page

* fix nbclassic url

* fix seealso blocks

* Fix note

* add changelog to the navbar

* update faq

* Update screencasts and screenshots

* Remove old screenshots and screencasts

* rename migrating file

* Split the migration guide

* dedicate a page to new features

* document themes

* Iterate on the new features

* expand docs on extensions

* add Binder link

* mention the interface dropdown

* iterate on features

* Mention nbgrader and RISE

* Lint

* Add server extension docs

* fixes

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: jtpio

docs/source/_static/images/blank-notebook-ui.png

@@ -4,6 +4,14 @@
 
 1. How do I install a prerelease version such as a beta or release candidate?
 
+You can install a prerelease version of the notebook using the `--pre` flag with `pip`:
+
 ```bash
 python -m pip install notebook --pre --upgrade
 ```
+
+If you are using `conda` or `mamba`, you can install a prerelease version of the notebook using the alpha or beta label. For example, to install the latest alpha release, you can run:
+
+```bash
+conda install -c conda-forge -c conda-forge/label/notebook_alpha notebook=7.0.0a18
+```

docs/source/_static/images/blank-notebook-ui.svg

@@ -6,12 +6,12 @@ This describes the basic steps to write a TypeScript extension for the Jupyter
 notebook front-end. This allows you to customize the behaviour of the various
 pages like the dashboard, the notebook, or the text editor.
 
-Starting with Notebook v7, front-end extensions for the notebook can be developed
+Starting with Notebook 7, front-end extensions for the notebook can be developed
 as prebuilt JupyterLab extensions.
 
-This means Notebook v7 is able to reuse many of the existing extensions from the JupyterLab ecosystem as is.
+This means Notebook 7 is able to reuse many of the existing extensions from the JupyterLab ecosystem as is.
 
-If you would like to develop a prebuilt extension for Notebook v7, check out:
+If you would like to develop a prebuilt extension for Notebook 7, check out:
 
 - [JupyterLab Extension Tutorial](https://jupyterlab.readthedocs.io/en/latest/extension/extension_tutorial.html): A tutorial to learn how to make a simple JupyterLab extension.
-- The [JupyterLab Extension Examples Repository](https://github.com/jupyterlab/extension-examples): A short tutorial series to learn how to develop extensions for JupyterLab by example.
+- The [JupyterLab Extension Examples Repository](https://github.com/jupyterlab/extension-examples): A repository containing many examples of JupyterLab extensions for performing various tasks: adding commands, adding a new widget, handling user settings, etc.

docs/source/_static/images/jupyter-file-editor.png

@@ -1,5 +1,20 @@
 # Extending the Notebook
 
+```{warning}
+Please note that the extension system for Notebook 7 is radically different
+from the one used in Notebook 6.5.x and earlier. If you are looking for
+information on how to extend the classic Notebook, please refer to the
+[documentation for NbClassic](https://nbclassic.readthedocs.io/en/latest/extending/index.html).
+```
+
+```{note}
+With Notebook 7 being developed on top of JupyterLab and Jupyter Server, the
+frontend extension system is now based on the same extension system used by JupyterLab.
+
+Server extensions are also now based on the same system used by Jupyter Server.
+You will find below a link to the relevant documentations.
+```
+
 Certain subsystems of the notebook server are designed to be extended or
 overridden by users. These documents explain these systems, and show how to
 override the notebook's defaults with your own custom behavior.

docs/source/_static/images/jupyter-notebook-dashboard.png

@@ -12,6 +12,7 @@
 
 user-documentation
 configuration
+migrating
 contributor
-migrate_to_notebook7
+changelog
 ```

docs/source/_static/images/jupyter-notebook-default.png

@@ -0,0 +1,46 @@
+# Migrating to Notebook 7
+
+```{warning}
+The Jupyter Notebook application is undergoing a major refactoring to
+improve the user experience and to make it easier to maintain and extend.
+
+This set of migration guides are intended to help you migrate your Classic Notebook
+setup and extensions to the new Jupyter Notebook 7, which is built on top of JupyterLab 4.
+```
+
+## Sunrising the Jupyter Notebook 7
+
+For the past few years, the Classic Jupyter Notebook has been in maintenance mode.
+
+Development has mostly moved to alternative user interfaces like JupyterLab, which is a more
+modern and extensible web application. This has resulted in a lot of new
+features and improvements in JupyterLab, but also in a lot of new features and
+improvements that were not possible to integrate to the Classic Notebook.
+
+For a while the plan was to progressively _sunset_ the Classic Notebook and not maintain it anymore. However, the Classic Notebook is still widely used and it is still the default user interface for Jupyter in many scenarios. Many users and organizations have not been able to switch to JupyterLab yet. For some users, JupyterLab can also be a more complex environment to use, especially for beginners.
+
+Following the feedback from the community, it was decided late 2021 to continue developing the Jupyter Notebook application and _sunrise_ it as Notebook 7. Notebook 7 is built on top of JupyterLab components and delivers new features like realtime collaboration, debugger, and theming.
+
+You can find more details about the changes currently taking place in the Jupyter Ecosystem in the [JEP 79] and [team-compass note].
+
+## New features in Notebook 7
+
+```{toctree}
+:maxdepth: 2
+
+notebook_7_features.md
+```
+
+## Migration Guides
+
+```{toctree}
+:maxdepth: 2
+
+migrating/frontend-extensions.md
+migrating/server-extensions.md
+migrating/custom-themes.md
+migrating/multiple-interfaces.md
+```
+
+[jep 79]: https://jupyter.org/enhancement-proposals/79-notebook-v7/notebook-v7.html
+[team-compass note]: https://github.com/jupyter/notebook-team-compass/issues/5#issuecomment-1085254000

docs/source/_static/images/jupyter-notebook-edit.png

@@ -0,0 +1,35 @@
+# Custom themes in Notebook 7
+
+In Notebook 7, the way to create custom themes has changed. This means that custom themes developed for Notebook 6 or earlier will not work with Notebook 7 and upwards.
+
+This is for example the case for community contributed themes such as [jupyter-themes](https://github.com/dunovank/jupyter-themes).
+
+## Using a custom theme
+
+Fortunately installing a custom theme for Notebook 7 is very easy. It is the same process as installing a regular extension.
+
+For exampe let's say you want to install the [JupyterLab Night](https://github.com/martinRenou/jupyterlab-night) theme. You can do so by running the following command:
+
+```bash
+pip install jupyterlab-night
+```
+
+Then refresh the page and you should see the new theme available in the settings menu:
+
+![a screencast showing how to install a custom theme](https://user-images.githubusercontent.com/591645/229583076-de3c0541-246f-4781-8941-fcbec2204038.gif)
+
+There are already many themes available on [PyPI](https://pypi.org/search/?q=jupyterlab-theme).
+
+You can also find other themes using the `jupyterlab-theme` topic on GitHub: https://github.com/topics/jupyterlab-theme
+
+For example:
+
+- [https://github.com/johnnybarrels/jupyterlab_onedarkpro](https://github.com/johnnybarrels/jupyterlab_onedarkpro)
+- [https://github.com/dunovank/jupyterlab_legos_ui](https://github.com/dunovank/jupyterlab_legos_ui)
+- [https://github.com/timkpaine/jupyterlab_miami_nights](https://github.com/timkpaine/jupyterlab_miami_nights)
+
+## Creating a custom theme
+
+Creating a custom theme for Notebook 7 follows the same process as creating a custom theme for JupyterLab 4.
+
+See the {ref}`Frontend Extension Guide <frontend-extensions>` to get you started. When creating the extension, select the `Theme` option in the cookiecutter prompt.

docs/source/_static/images/new-notebook.gif

@@ -0,0 +1,33 @@
+# Frontend Extensions in Notebook 7
+
+```{warning}
+Any extension developed for Notebook \< 7 or NbClassic will not be
+compatible with Notebook 7 and upwards.
+
+Some extensions like nbgrader have already been ported. We invite you to
+check if the extensions you are using have already been ported.
+```
+
+You can check the following resources to see if your extension is available for Notebook 7:
+
+## List of available Notebook 7 extensions
+
+To get an idea of the extensions available for Notebook 7, you can check the following resources:
+
+- [List of JupyterLab extensions][list of jupyterlab extensions]
+- [Awesome Jupyter][awesome jupyter]
+
+These resources are for JupyterLab, but many of them are compatible with Notebook 7 since Notebook 7 is based on JupyterLab.
+
+[list of jupyterlab extensions]: https://jupyterlab-contrib.github.io/extensions.html
+[awesome jupyter]: https://github.com/markusschanta/awesome-jupyter#jupyterlab-extensions
+
+## JupyterLab equivalent extensions to the Classic Notebook
+
+The `jupyterlab-contrib` organization maintains a list of extensions to ease the transition from the Classic Notebook to Notebook 7 and / or JupyterLab.
+
+The list is available at the following URL: [Migrating from the Classic Notebook][migrate from classic]
+
+![a screenshot showing extensions in classic and lab](https://user-images.githubusercontent.com/591645/229616855-94d34762-6666-4edd-a969-e85b285d7094.png)
+
+[migrate from classic]: https://jupyterlab-contrib.github.io/migrate_from_classical.html

docs/source/development_faq.md

@@ -1,24 +1,34 @@
-# Migrating to Notebook 7
+# Simultaneous usage of different versions of Notebook 7 and the Classic Notebook UI
 
-## Build Jupyter Notebook v7 off of JupyterLab components
+With the release of Notebook 7, the classic Notebook UI is now
+available as a Jupyter Server extension, NbClassic. This means that
+NbClassic can be installed independently of Notebook 7, and can be also
+installed alongside Notebook 7.
 
-Read more details about the changes currently taking place in the
-Jupyter Ecosystem in the [JEP 79] and [team-compass note].
+Below are different scenarios that you might consider when updating to Notebook 7.
 
-Notebook 7 is built on top of JupyterLab components and delivers new features
-like realtime collaboration, debugger, theming.
+## Try it on Binder
 
-## Compatibility with older versions
+You can try JupyterLab, Notebook 7 and NBClassic installed together using [this gist][lab-nb-nbclassic] on Binder:
 
-Any extension developed for Notebook \< 7 or NbClassic will not be
-compatible with Notebook 7 and upwards.
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gist/jtpio/35a72862c8be13dee31b61ebac2d9786/master?urlpath=/tree)
 
-Some extensions like nbgrader have already been ported. We invite you to
-check if the extensions you are using have already been ported.
+[lab-nb-nbclassic]: https://gist.github.com/jtpio/35a72862c8be13dee31b61ebac2d9786
 
-## Simultaneous usage of different versions
+## Using the `Interface` dropdown
 
-**NbClassic and Notebook 7**
+Notebook 7 provides a dropdown menu to switch between the different user interfaces available on the same server.
+
+It is available in the Notebook toolbar:
+
+![image](https://user-images.githubusercontent.com/591645/229729077-a91bc9dd-9bb9-4510-a266-599bf2f97745.png)
+
+```{note}
+This dropdown is only available when using Notebook 7 or JupyterLab.
+It is not displayed when using NbClassic.
+```
+
+## NbClassic and Notebook 7
 
 You can install NbClassic, Notebook 7 and JupyterLab, all three of
 which will provide different user interfaces
@@ -30,7 +40,7 @@ dependency of Notebook 7, and these front ends will be available
 through the following base paths: JupyterLab at `/lab`, Notebook 7 at
 `/tree`, and NbClassic at `/nbclassic/tree`.
 
-**NbClassic and Notebook 6.5.x**
+## NbClassic and Notebook 6.5.x
 
 As NbClassic provides the static assets for Notebook 6.5.x, while
 having both installed should cause no issues, the user interface provided
@@ -42,7 +52,7 @@ static assets. When starting an instance of JupyterLab you will be able
 to access the classic view of Notebook with NbClassic served on the same
 server at `/tree`.
 
-**NbClassic and Notebook \<= 6.4.x**
+## NbClassic and Notebook \<= 6.4.x
 
 When using NbClassic and Notebook \<= 6.4.x you can expect that these UIs
 will not be only presented at different servers, meaning they will both
@@ -52,20 +62,20 @@ reflected in Notebook versions \<= 6.4.x. In this case as well, you would
 be able to access the classic view of Notebook with NbClassic served on
 the same server, at `/tree`.
 
-**NbClassic and JupyterLab 3.x**
+## NbClassic and JupyterLab 3.x
 
 When only JupyterLab 3.x is installed, then NbClassic does not have to be
 explicitly installed as JupyterLab 3.x depends on it. They will run on
 the same server, and are reachable via `/tree` for NbClassic and
 `/lab` for JupyterLab.
 
-**NbClassic and JupyterLab 4.x**
+## NbClassic and JupyterLab 4.x
 
 When only JupyterLab 4.x is installed, then NbClassic has to be installed
 explictly. They will run on the same server, and are reachable via
 `/tree` for NbClassic, and `/lab` for JupyterLab.
 
-**NbClassic Independently**
+## NbClassic Independently
 
 When you choose to install only NbClassic via `pip install nbclassic`,
 the classic Notebook UI will be presented at the `/tree` path. As the
@@ -76,6 +86,3 @@ way to view the NbClassic frontend. You would be able to manually
 enable the extension when running an instance of Jupyter Server,
 `> jupyter server --ServerApp.jpserver_extensions="nbclassic=True"`,
 which will provide the NbClassic frontend at `/tree` path when visited.
-
-[jep 79]: https://jupyter.org/enhancement-proposals/79-notebook-v7/notebook-v7.html
-[team-compass note]: https://github.com/jupyter/notebook-team-compass/issues/5#issuecomment-1085254000

docs/source/extending/frontend_extensions.md

@@ -0,0 +1,13 @@
+# Server Extensions in Notebook 7
+
+Notebook 7 is now based on Jupyter Server, which is a new server application that allows to run multiple Jupyter applications (e.g. Notebook, JupyterLab, NBClassic, etc.) on the same server.
+
+This means that Notebook 7 is able to reuse many of the existing server extensions from the Jupyter ecosystem as is.
+
+## Migration from the Notebook Server
+
+The Jupyter Server documentation provides a [guide for migrating from the classic notebook server to Jupyter Server](https://jupyter-server.readthedocs.io/en/latest/operators/migrate-from-nbserver.html)
+
+## Authoring Server Extensions
+
+The Jupyter Server documentation provides a [guide for authoring server extensions](https://jupyter-server.readthedocs.io/en/latest/developers/extensions.html)