jupyter · jtpio · Mar 14, 2023 · Mar 14, 2023 · Mar 14, 2023 · Mar 14, 2023
diff --git a/docs/source/config_overview.md b/docs/source/config_overview.md
@@ -0,0 +1,63 @@
+(configuration-overview)=
+
+# Configuration Overview
+
+Beyond the default configuration settings, you can configure a rich array of
+options to suit your workflow. Here are areas that are commonly configured
+when using Jupyter Notebook:
+
+> - {ref}`Jupyter's common configuration system <configure-common>`
+> - {ref}`Jupyter Server <configure-jupyter-server>`
+> - {ref}`Notebook extensions <configure-nbextensions>`
+
+Let's look at highlights of each area.
+
+(configure-common)=
+
+## Jupyter's Common Configuration system
+
+Jupyter applications, from the Notebook to JupyterHub to nbgrader, share a
+common configuration system. The process for creating a configuration file
+and editing settings is similar for all the Jupyter applications.
+
+> - [Jupyter’s Common Configuration Approach](https://jupyter.readthedocs.io/en/latest/use/config.html)
+> - [Common Directories and File Locations](https://jupyter.readthedocs.io/en/latest/use/jupyter-directories.html)
+> - [Language kernels](https://jupyter.readthedocs.io/en/latest/projects/kernels.html)
+> - [traitlets](https://traitlets.readthedocs.io/en/latest/config.html#module-traitlets.config)
+>   provide a low-level architecture for configuration.
+
+(configure-jupyter-server)=
+
+## Jupyter server
+
+The Jupyter Server runs the language kernel and communicates with the
+front-end Notebook client (i.e. the familiar notebook interface).
+
+> - Configuring the Jupyter Server
+>
+>   > To create a `jupyter_server_config.py` file in the `.jupyter`
+>   > directory, with all the defaults commented out, use the following
+>   > command:
+>   >
+>   > ```
+>   > $ jupyter server --generate-config
+>   > ```
+>
+> - [Running a Jupyter Server](https://jupyter-server.readthedocs.io/en/stable/operators/public-server.html)
+>
+> - 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.
+
+(configure-nbextensions)=
+
+## Notebook extensions
+
+The Notebook frontend can be extending with JupyterLab extensions.
+
+See the {ref}`Frontend Extension Guide <frontend-extensions>` for more information.
+
+[Security in Jupyter notebooks:](https://jupyter-server.readthedocs.io/en/stable/operators/security.html)
+Since security policies vary from organization to organization, we encourage you to
+consult with your security team on settings that would be best for your use
+cases. Our documentation offers some responsible security practices, and we
+recommend becoming familiar with the practices.
diff --git a/docs/source/config_overview.rst b/docs/source/config_overview.rst
diff --git a/docs/source/configuration.md b/docs/source/configuration.md
@@ -0,0 +1,10 @@
+# Configuration
+
+```{toctree}
+:caption: Configuration
+:maxdepth: 1
+
+config_overview
+Security <https://jupyter-server.readthedocs.io/en/stable/operators/security.html>
+extending/index.rst
+```
diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst
diff --git a/docs/source/contributor.md b/docs/source/contributor.md
@@ -0,0 +1,9 @@
+# Contributor
+
+```{toctree}
+:caption: Contributor Documentation
+:maxdepth: 1
+
+contributing
+development_faq
+```
diff --git a/docs/source/contributor.rst b/docs/source/contributor.rst
diff --git a/docs/source/development_faq.md b/docs/source/development_faq.md
@@ -0,0 +1,9 @@
+(development-faq)=
+
+# Developer FAQ
+
+1. How do I install a prerelease version such as a beta or release candidate?
+
+```bash
+python -m pip install notebook --pre --upgrade
+```
diff --git a/docs/source/development_faq.rst b/docs/source/development_faq.rst
diff --git a/.../source/extending/frontend_extensions.rst → docs/source/extending/frontend_extensions.md b/.../source/extending/frontend_extensions.rst → docs/source/extending/frontend_extensions.md
@@ -1,8 +1,6 @@
-.. _frontend_extensions:
+(frontend-extensions)=
 
-===========================
-Custom front-end extensions
-===========================
+# Custom front-end extensions
 
 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
@@ -15,5 +13,5 @@ This means Notebook v7 is able to reuse many of the existing extensions from the
 
 If you would like to develop a prebuilt extension for Notebook v7, 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.
+- [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.
diff --git a/docs/source/extending/index.md b/docs/source/extending/index.md
@@ -0,0 +1,12 @@
+# Extending the Notebook
+
+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.
+
+```{toctree}
+:maxdepth: 2
+
+Extending the Jupyter Server <https://jupyter-server.readthedocs.io/en/stable/developers/index.html>
+frontend_extensions
+```
diff --git a/docs/source/extending/index.rst b/docs/source/extending/index.rst
diff --git a/docs/source/index.md b/docs/source/index.md
@@ -0,0 +1,17 @@
+# The Jupyter Notebook
+
+```{image} ./_static/images/notebook-running-code.png
+
+```
+
+- [Installation](https://jupyter.readthedocs.io/en/latest/install.html)
+- [Starting the Notebook](https://jupyter.readthedocs.io/en/latest/running.html)
+
+```{toctree}
+:maxdepth: 2
+
+user-documentation
+configuration
+contributor
+migrate_to_notebook7
+```
diff --git a/docs/source/index.rst b/docs/source/index.rst
diff --git a/docs/source/migrate_to_notebook7.rst → docs/source/migrate_to_notebook7.md b/docs/source/migrate_to_notebook7.rst → docs/source/migrate_to_notebook7.md
@@ -1,85 +1,81 @@
-Migrating to Notebook 7
-=======================
+# Migrating to Notebook 7
 
-Build Jupyter Notebook v7 off of JupyterLab components
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+## Build Jupyter Notebook v7 off of JupyterLab components
 
 Read more details about the changes currently taking place in the
-Jupyter Ecosystem in the `JEP 79`_ and `team-compass note`_.
+Jupyter Ecosystem in the [JEP 79] and [team-compass note].
 
 Notebook 7 is built on top of JupyterLab components and delivers new features
 like realtime collaboration, debugger, theming.
 
-Compatibility with older versions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+## Compatibility with older versions
 
-Any extension developed for Notebook < 7 or NbClassic will not be
+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.
 
-Simulaneous usage of different versions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+## Simulaneous usage of different versions
 
 **NbClassic and Notebook 7**
 
 You can install NbClassic, Notebook 7 and JupyterLab, all three of
 which will provide different user interfaces
 on the same server. When Notebook 7 is available, the NbClassic UI, will
-be served at the ``/nbclassic/tree`` base path rather than the
-base path ``/tree`` used otherwise. If you are using Notebook 7 along
+be served at the `/nbclassic/tree` base path rather than the
+base path `/tree` used otherwise. If you are using Notebook 7 along
 with NbClassic, you will also have JupyterLab installed as it is a
 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``.
+through the following base paths: JupyterLab at `/lab`, Notebook 7 at
+`/tree`, and NbClassic at `/nbclassic/tree`.
 
 **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
 by these two packages will be the same. These UIs will be served by
 different back end servers. An NbClassic instance will be at a server with the
-``/tree`` path and opening a Notebook 6.5.x instance will open on a
-different server with the ``/tree`` path as well, presenting the same
+`/tree` path and opening a Notebook 6.5.x instance will open on a
+different server with the `/tree` path as well, presenting the same
 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``.
+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
+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
-be available at their respective server under ``/tree`` but they
+be available at their respective server under `/tree` but they
 may also differ as potential changes to the NbClassic UI will not be
-reflected in Notebook versions <= 6.4.x. In this case as well, you would
+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``.
+the same server, at `/tree`.
 
 **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.
+the same server, and are reachable via `/tree` for NbClassic and
+`/lab` for JupyterLab.
 
 **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.
+`/tree` for NbClassic, and `/lab` for JupyterLab.
 
 **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
+When you choose to install only NbClassic via `pip install nbclassic`,
+the classic Notebook UI will be presented at the `/tree` path. As the
 other frontends are not installed, attempting to access the other paths
 will return errors. Note that NbClassic being a Jupyter Server extension,
 indicated Jupyter Server will be available. This provides an additional
-way to view the NbClassic frontend. You would be able to  manually
+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.
+`> 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
+[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