From 99db9423e34e4c1afc0f0ddbb01e86d4099bcd75 Mon Sep 17 00:00:00 2001
From: "Lumberbot (aka Jack)"
 <39504233+meeseeksmachine@users.noreply.github.com>
Date: Thu, 8 Feb 2024 17:12:31 +0100
Subject: [PATCH] Backport PR #7244 on branch 7.0.x (Add documentation for
 updating `notebook` imports) (#7245)

* Backport PR #7244: Add documentation for updating `notebook` imports

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: Jeremy Tuloup <jeremy.tuloup@gmail.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 docs/source/configuring/config_overview.md |  6 ++++
 docs/source/migrate_to_notebook7.md        |  1 +
 docs/source/migrating/server-imports.md    | 37 ++++++++++++++++++++++
 3 files changed, 44 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..6d694d15a9
--- /dev/null
+++ b/docs/source/migrating/server-imports.md
@@ -0,0 +1,37 @@
+# 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.