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](https://github.com/python-jsonschema/check-jsonschema/compare/0.21.0...0.22.0) - [github.com/psf/black: 23.1.0 → 23.3.0](https://github.com/psf/black/compare/23.1.0...23.3.0) - [github.com/charliermarsh/ruff-pre-commit: v0.0.254 → v0.0.260](https://github.com/charliermarsh/ruff-pre-commit/compare/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>pull/6816/head
Jeremy Tuloup
3 years ago
committed by
GitHub
parent
65da1cd756
commit
0c888aedee
|
Before Width: | Height: | Size: 25 KiB |
|
Before Width: | Height: | Size: 25 KiB |
|
Before Width: | Height: | Size: 262 KiB |
|
Before Width: | Height: | Size: 66 KiB |
|
Before Width: | Height: | Size: 161 KiB |
|
Before Width: | Height: | Size: 218 KiB |
|
Before Width: | Height: | Size: 518 KiB |
@ -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
|
||||
@ -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:
|
||||
|
||||
|
||||
|
||||
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.
|
||||
@ -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]
|
||||
|
||||
|
||||
|
||||
[migrate from classic]: https://jupyterlab-contrib.github.io/migrate_from_classical.html
|
||||
@ -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)
|
||||
@ -0,0 +1,148 @@
|
||||
# New features in Notebook 7
|
||||
|
||||
This document describes the new features in Notebook 7 as originally mentioned in the related Jupyter Enhancement Proposal [JEP 79][jep 79].
|
||||
|
||||
```{contents} Table of Contents
|
||||
:depth: 3
|
||||
:local:
|
||||
```
|
||||
|
||||
## Debugger
|
||||
|
||||
Notebook 7 includes a new debugger that allows you to step through your code cell by cell. You can also set breakpoints and inspect variables.
|
||||
|
||||
|
||||
|
||||
## Real Time collaboration
|
||||
|
||||
Notebook 7 allows for using the real time collaboration extension so you can share your notebook with other users and edit it in real time.
|
||||
|
||||
The Real Time Collaboration feature is the same as in JupyterLab and is available as a JupyterLab extension. It is not enabled by default, but you can install with `pip`:
|
||||
|
||||
```bash
|
||||
pip install jupyter-collaboration
|
||||
```
|
||||
|
||||
or with `conda`:
|
||||
|
||||
```bash
|
||||
conda install -c conda-forge jupyter-collaboration
|
||||
```
|
||||
|
||||
After installing the extension, restart the Jupyter Server so the extension can be loaded.
|
||||
|
||||
```{note}
|
||||
It is possible for two users to work on the same notebook using Notebook 7 or JupyterLab.
|
||||
```
|
||||
|
||||
## Table of Contents
|
||||
|
||||
Notebook 7 includes a new table of contents extension that allows you to navigate through your notebook using a sidebar. The Table of Contents is built-in and enabled by default, just like in JupyterLab.
|
||||
|
||||
|
||||
|
||||
## Theming and Dark Mode
|
||||
|
||||
A Dark Theme is now available in the Jupyter Notebook by default. You can also install other themes as JupyterLab extensions.
|
||||
|
||||
|
||||
|
||||
You can also install many other JupyterLab themes. For example to install the [JupyterLab Night](https://github.com/martinRenou/jupyterlab-night) theme:
|
||||
|
||||
```shell
|
||||
pip install jupyterlab-night
|
||||
```
|
||||
|
||||
Then refresh the page and select the new theme in the settings:
|
||||
|
||||
|
||||
|
||||
## Internationalization
|
||||
|
||||
Notebook 7 now provides the ability to set the display language of the user interface.
|
||||
|
||||
Users will need to install the language pack as a separate Python package. Language packs are grouped in the [language packs repository on GitHub](https://github.com/jupyterlab/language-packs/), and can be installed with `pip`. For example, it is possible to install the language pack for French (France) using the following command:
|
||||
|
||||
```shell
|
||||
pip install jupyterlab-language-pack-fr-FR
|
||||
```
|
||||
|
||||
After installing the language pack, reload the page and the new language should be available in the settings.
|
||||
|
||||
|
||||
|
||||
```{note}
|
||||
Notebook 7 and JupyterLab share the same language packs, so it is possible to use the same language pack in both applications.
|
||||
```
|
||||
|
||||
## Improved Web Content Accessibility Guidelines (WCAG) compliance
|
||||
|
||||
Improving the accessibility of Jupyter had long been impeded by significant obstacles. The primary obstacle was that the text editor underlying the Jupyter Notebook (CodeMirror 5) had major accessibility issues.
|
||||
|
||||
Fortunately, this accessibility bottleneck has been unblocked as JupyterLab has been upgraded to use CodeMirror 6, a complete rewrite of the text editor with a strong focus on accessibility. Although this upgrade required extensive codebase modifications, the changes is available with JupyterLab 4. By being built on top of JupyterLab, Jupyter Notebook 7 directly benefits from the CodeMirror 6 upgrade.
|
||||
|
||||
|
||||
|
||||
Check out the related blog post for more details: [Improving the accessibility of Jupyter](https://blog.jupyter.org/improving-the-accessibility-of-jupyter-6c695db518d3).
|
||||
|
||||
## Support for many JupyterLab extensions
|
||||
|
||||
Notebook 7 is based on JupyterLab and therefore supports many of the existing JupyterLab extensions.
|
||||
|
||||
You can install JupyterLab extensions with `pip` or `conda`. For example to install the LSP (Language Server Protocol) extension for enhanced code completion, you can use the following commands:
|
||||
|
||||
```bash
|
||||
pip install jupyter-lsp
|
||||
```
|
||||
|
||||
```bash
|
||||
conda install -c conda-forge jupyter-lsp
|
||||
```
|
||||
|
||||
Popular extensions like `nbgrader` and `RISE` have already been ported to work with Notebook 7.
|
||||
|
||||
### nbgrader
|
||||
|
||||
```{note}
|
||||
The nbgrader extension is still under active development and a version compatible with Notebook 7 is not yet available on PyPI.
|
||||
However a version compatible with Notebook 7 will be available before the final release of Notebook 7.
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
### RISE
|
||||
|
||||
```{warning}
|
||||
The RISE extension is still under active development and a version compatible with Notebook 7 is not yet available on PyPI.
|
||||
```
|
||||
|
||||
The RISE extension is another popular JupyterLab extension that is being ported to work with Notebook 7. It allows you to turn your Jupyter Notebooks into a slideshow.
|
||||
|
||||
The extension is still under [active development](https://github.com/jupyterlab-contrib/rise). When ready, it will be possible to install it with `pip`:
|
||||
|
||||
```bash
|
||||
pip install jupyterlab-rise
|
||||
```
|
||||
|
||||
## A document-centric user experience
|
||||
|
||||
Despite all the new features and as stated in [JEP 79][jep 79], Notebook 7 keeps the document-centric user experience of the Classic Notebook:
|
||||
|
||||
> The Jupyter Notebook application offers a document-centric user experience. That is, in the Notebook application, the landing page that contains a file manager, running tools tab, and a few optional extras, is a launching point into opening standalone, individual documents. This document-centric experience is important for many users, and that is the first key point this proposal aims to preserve. Notebook v7 will be based on a different JavaScript implementation than v6, but it will preserve the document-centric experience, where each individual notebook opens in a separate browser tab and the visible tools and menus are focused on the open document.
|
||||
|
||||
[jep 79]: https://jupyter.org/enhancement-proposals/79-notebook-v7/notebook-v7.html
|
||||
|
||||
## Compact View on Mobile Devices
|
||||
|
||||
Notebook 7 automatically switches to a more compact layout on mobile devices, making it convenient to run code on the go.
|
||||
|
||||
|
||||
|
||||
## References
|
||||
|
||||
This was just a quick overview of the new features in Notebook 7. For more details, you can check out the following resources:
|
||||
|
||||
- The [JupyterLab Documentation](https://jupyterlab.readthedocs.io/en/latest/) is a great resource to learn more about JupyterLab and the extensions available. Since Notebook 7 is based on JupyterLab, many of the features and extensions available for JupyterLab are also available for Notebook 7.
|
||||
- [Migration Guide](./migrating.md) for Notebook 7, which explains how to migrate from the Classic Notebook to Notebook 7.
|
||||
Loading…
Reference in new issue