From aef8e95fc5c60c0aa37192fddc2e70239d824516 Mon Sep 17 00:00:00 2001
From: Jeremy Tuloup <jeremy.tuloup@gmail.com>
Date: Thu, 8 Feb 2024 16:23:55 +0100
Subject: [PATCH] Add documentation for updating `notebook` imports (#7244)

* Add documentation for updating `notebook` imports

* fix typos
---
 docs/source/configuring/config_overview.md |  6 ++++
 docs/source/migrate_to_notebook7.md        |  1 +
 docs/source/migrating/server-imports.md    | 33 ++++++++++++++++++++++
 3 files changed, 40 insertions(+)
 create mode 100644 docs/source/migrating/server-imports.md

diff --git a/docs/source/configuring/config_overview.md b/docs/source/configuring/config_overview.md
index d2288186ae..3755b2db30 100644
--- a/docs/source/configuring/config_overview.md
+++ b/docs/source/configuring/config_overview.md
@@ -52,6 +52,12 @@ front-end Notebook client (i.e. the familiar notebook interface).
 > - Related: [Configuring a language kernel](https://ipython.readthedocs.io/en/latest/install/kernel_install.html)
 >   to run in the Jupyter Server enables your server to run other languages, like R or Julia.
 
+```{warning}
+Jupyter Notebook 7 is now based on Jupyter Server. This may break some previous `notebook` imports you may have been using, such as `notebook.auth` or `notebook.notebookapp`.
+
+Check out the [migration guide](../migrating/server-imports.md) to learn more on how to update these server imports.
+```
+
 (configure-nbextensions)=
 
 ## Notebook extensions
diff --git a/docs/source/migrate_to_notebook7.md b/docs/source/migrate_to_notebook7.md
index 91c6c1ef81..0806a4c188 100644
--- a/docs/source/migrate_to_notebook7.md
+++ b/docs/source/migrate_to_notebook7.md
@@ -73,6 +73,7 @@ notebook_7_features.md
 
 migrating/frontend-extensions.md
 migrating/server-extensions.md
+migrating/server-imports.md
 migrating/custom-themes.md
 migrating/multiple-interfaces.md
 ```
diff --git a/docs/source/migrating/server-imports.md b/docs/source/migrating/server-imports.md
new file mode 100644
index 0000000000..c00f808209
--- /dev/null
+++ b/docs/source/migrating/server-imports.md
@@ -0,0 +1,33 @@
+# Server Imports in Notebook 7
+
+Notebook 7 is now based on Jupyter Server, which lets users run multiple Jupyter frontends (e.g. Notebook, JupyterLab, NBClassic, etc.) on the same server.
+
+Prior to Notebook 7, the Classic Notebook server included the server modules in the `notebook` package. This means it was possible to import the server modules from the `notebook` package, for example:
+
+```python
+from notebook.auth import passwd
+passwd("foo")
+```
+
+Or:
+
+```python
+from notebook import notebookapp
+notebookapp.list_running_servers()
+```
+
+In Notebook 7, these server modules are now exposed by the `jupyter_server` package. The code snippets above should be updated to:
+
+```python
+from jupyter_server.auth import passwd
+passwd("foo")
+```
+
+And:
+
+```python
+from jupyter_server import serverapp
+serverapp.list_running_servers()
+```
+
+These are just examples, so you may have to adjust your use of `notebook` imports based on the specific server modules you were using.