Skip to content

Commit f05e5a9

Browse files
jtpiojtpio
authored
Convert docs to Markdown (#6770)
* Convert docs to Markdown * lint * update refs * more update
1 parent f44ac97 commit f05e5a9

20 files changed

+590
-615
lines changed

‎docs/source/config_overview.md

+63
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
(configuration-overview)=
2+
3+
# Configuration Overview
4+
5+
Beyond the default configuration settings, you can configure a rich array of
6+
options to suit your workflow. Here are areas that are commonly configured
7+
when using Jupyter Notebook:
8+
9+
> - {ref}`Jupyter's common configuration system <configure-common>`
10+
> - {ref}`Jupyter Server <configure-jupyter-server>`
11+
> - {ref}`Notebook extensions <configure-nbextensions>`
12+
13+
Let's look at highlights of each area.
14+
15+
(configure-common)=
16+
17+
## Jupyter's Common Configuration system
18+
19+
Jupyter applications, from the Notebook to JupyterHub to nbgrader, share a
20+
common configuration system. The process for creating a configuration file
21+
and editing settings is similar for all the Jupyter applications.
22+
23+
> - [Jupyter’s Common Configuration Approach](https://jupyter.readthedocs.io/en/latest/use/config.html)
24+
> - [Common Directories and File Locations](https://jupyter.readthedocs.io/en/latest/use/jupyter-directories.html)
25+
> - [Language kernels](https://jupyter.readthedocs.io/en/latest/projects/kernels.html)
26+
> - [traitlets](https://traitlets.readthedocs.io/en/latest/config.html#module-traitlets.config)
27+
> provide a low-level architecture for configuration.
28+
29+
(configure-jupyter-server)=
30+
31+
## Jupyter server
32+
33+
The Jupyter Server runs the language kernel and communicates with the
34+
front-end Notebook client (i.e. the familiar notebook interface).
35+
36+
> - Configuring the Jupyter Server
37+
>
38+
> > To create a `jupyter_server_config.py` file in the `.jupyter`
39+
> > directory, with all the defaults commented out, use the following
40+
> > command:
41+
> >
42+
> > ```
43+
> > $ jupyter server --generate-config
44+
> > ```
45+
>
46+
> - [Running a Jupyter Server](https://jupyter-server.readthedocs.io/en/stable/operators/public-server.html)
47+
>
48+
> - Related: [Configuring a language kernel](https://ipython.readthedocs.io/en/latest/install/kernel_install.html)
49+
> to run in the Jupyter Server enables your server to run other languages, like R or Julia.
50+
51+
(configure-nbextensions)=
52+
53+
## Notebook extensions
54+
55+
The Notebook frontend can be extending with JupyterLab extensions.
56+
57+
See the {ref}`Frontend Extension Guide <frontend-extensions>` for more information.
58+
59+
[Security in Jupyter notebooks:](https://jupyter-server.readthedocs.io/en/stable/operators/security.html)
60+
Since security policies vary from organization to organization, we encourage you to
61+
consult with your security team on settings that would be best for your use
62+
cases. Our documentation offers some responsible security practices, and we
63+
recommend becoming familiar with the practices.

‎docs/source/config_overview.rst

-63
This file was deleted.

‎docs/source/configuration.md

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Configuration
2+
3+
```{toctree}
4+
:caption: Configuration
5+
:maxdepth: 1
6+
7+
config_overview
8+
Security <https://jupyter-server.readthedocs.io/en/stable/operators/security.html>
9+
extending/index.rst
10+
```

‎docs/source/configuration.rst

-11
This file was deleted.

‎docs/source/contributor.md

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Contributor
2+
3+
```{toctree}
4+
:caption: Contributor Documentation
5+
:maxdepth: 1
6+
7+
contributing
8+
development_faq
9+
```

‎docs/source/contributor.rst

-10
This file was deleted.

‎docs/source/development_faq.md

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
(development-faq)=
2+
3+
# Developer FAQ
4+
5+
1. How do I install a prerelease version such as a beta or release candidate?
6+
7+
```bash
8+
python -m pip install notebook --pre --upgrade
9+
```

‎docs/source/development_faq.rst

-10
This file was deleted.

‎docs/source/extending/frontend_extensions.rst ‎docs/source/extending/frontend_extensions.md

+4-6
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,6 @@
1-
.. _frontend_extensions:
1+
(frontend-extensions)=
22

3-
===========================
4-
Custom front-end extensions
5-
===========================
3+
# Custom front-end extensions
64

75
This describes the basic steps to write a TypeScript extension for the Jupyter
86
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
1513

1614
If you would like to develop a prebuilt extension for Notebook v7, check out:
1715

18-
- `JupyterLab Extension Tutorial <https://jupyterlab.readthedocs.io/en/latest/extension/extension_tutorial.html>`_: A tutorial to learn how to make a simple JupyterLab extension.
19-
- 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.
16+
- [JupyterLab Extension Tutorial](https://jupyterlab.readthedocs.io/en/latest/extension/extension_tutorial.html): A tutorial to learn how to make a simple JupyterLab extension.
17+
- 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.

‎docs/source/extending/index.md

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Extending the Notebook
2+
3+
Certain subsystems of the notebook server are designed to be extended or
4+
overridden by users. These documents explain these systems, and show how to
5+
override the notebook's defaults with your own custom behavior.
6+
7+
```{toctree}
8+
:maxdepth: 2
9+
10+
Extending the Jupyter Server <https://jupyter-server.readthedocs.io/en/stable/developers/index.html>
11+
frontend_extensions
12+
```

‎docs/source/extending/index.rst

-13
This file was deleted.

‎docs/source/index.md

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# The Jupyter Notebook
2+
3+
```{image} ./_static/images/notebook-running-code.png
4+
5+
```
6+
7+
- [Installation](https://jupyter.readthedocs.io/en/latest/install.html)
8+
- [Starting the Notebook](https://jupyter.readthedocs.io/en/latest/running.html)
9+
10+
```{toctree}
11+
:maxdepth: 2
12+
13+
user-documentation
14+
configuration
15+
contributor
16+
migrate_to_notebook7
17+
```

‎docs/source/index.rst

-17
This file was deleted.

‎docs/source/migrate_to_notebook7.rst ‎docs/source/migrate_to_notebook7.md

+28-32
Original file line numberDiff line numberDiff line change
@@ -1,85 +1,81 @@
1-
Migrating to Notebook 7
2-
=======================
1+
# Migrating to Notebook 7
32

4-
Build Jupyter Notebook v7 off of JupyterLab components
5-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3+
## Build Jupyter Notebook v7 off of JupyterLab components
64

75
Read more details about the changes currently taking place in the
8-
Jupyter Ecosystem in the `JEP 79`_ and `team-compass note`_.
6+
Jupyter Ecosystem in the [JEP 79] and [team-compass note].
97

108
Notebook 7 is built on top of JupyterLab components and delivers new features
119
like realtime collaboration, debugger, theming.
1210

13-
Compatibility with older versions
14-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
11+
## Compatibility with older versions
1512

16-
Any extension developed for Notebook < 7 or NbClassic will not be
13+
Any extension developed for Notebook \< 7 or NbClassic will not be
1714
compatible with Notebook 7 and upwards.
1815

1916
Some extensions like nbgrader have already been ported. We invite you to
2017
check if the extensions you are using have already been ported.
2118

22-
Simulaneous usage of different versions
23-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
19+
## Simulaneous usage of different versions
2420

2521
**NbClassic and Notebook 7**
2622

2723
You can install NbClassic, Notebook 7 and JupyterLab, all three of
2824
which will provide different user interfaces
2925
on the same server. When Notebook 7 is available, the NbClassic UI, will
30-
be served at the ``/nbclassic/tree`` base path rather than the
31-
base path ``/tree`` used otherwise. If you are using Notebook 7 along
26+
be served at the `/nbclassic/tree` base path rather than the
27+
base path `/tree` used otherwise. If you are using Notebook 7 along
3228
with NbClassic, you will also have JupyterLab installed as it is a
3329
dependency of Notebook 7, and these front ends will be available
34-
through the following base paths: JupyterLab at ``/lab``, Notebook 7 at
35-
``/tree``, and NbClassic at ``/nbclassic/tree``.
30+
through the following base paths: JupyterLab at `/lab`, Notebook 7 at
31+
`/tree`, and NbClassic at `/nbclassic/tree`.
3632

3733
**NbClassic and Notebook 6.5.x**
3834

3935
As NbClassic provides the static assets for Notebook 6.5.x, while
4036
having both installed should cause no issues, the user interface provided
4137
by these two packages will be the same. These UIs will be served by
4238
different back end servers. An NbClassic instance will be at a server with the
43-
``/tree`` path and opening a Notebook 6.5.x instance will open on a
44-
different server with the ``/tree`` path as well, presenting the same
39+
`/tree` path and opening a Notebook 6.5.x instance will open on a
40+
different server with the `/tree` path as well, presenting the same
4541
static assets. When starting an instance of JupyterLab you will be able
4642
to access the classic view of Notebook with NbClassic served on the same
47-
server at ``/tree``.
43+
server at `/tree`.
4844

49-
**NbClassic and Notebook <= 6.4.x**
45+
**NbClassic and Notebook \<= 6.4.x**
5046

51-
When using NbClassic and Notebook <= 6.4.x you can expect that these UIs
47+
When using NbClassic and Notebook \<= 6.4.x you can expect that these UIs
5248
will not be only presented at different servers, meaning they will both
53-
be available at their respective server under ``/tree`` but they
49+
be available at their respective server under `/tree` but they
5450
may also differ as potential changes to the NbClassic UI will not be
55-
reflected in Notebook versions <= 6.4.x. In this case as well, you would
51+
reflected in Notebook versions \<= 6.4.x. In this case as well, you would
5652
be able to access the classic view of Notebook with NbClassic served on
57-
the same server, at ``/tree``.
53+
the same server, at `/tree`.
5854

5955
**NbClassic and JupyterLab 3.x**
6056

6157
When only JupyterLab 3.x is installed, then NbClassic does not have to be
6258
explicitly installed as JupyterLab 3.x depends on it. They will run on
63-
the same server, and are reachable via ``/tree`` for NbClassic and
64-
``/lab`` for JupyterLab.
59+
the same server, and are reachable via `/tree` for NbClassic and
60+
`/lab` for JupyterLab.
6561

6662
**NbClassic and JupyterLab 4.x**
6763

6864
When only JupyterLab 4.x is installed, then NbClassic has to be installed
6965
explictly. They will run on the same server, and are reachable via
70-
``/tree`` for NbClassic, and ``/lab`` for JupyterLab.
66+
`/tree` for NbClassic, and `/lab` for JupyterLab.
7167

7268
**NbClassic Independently**
7369

74-
When you choose to install only NbClassic via ``pip install nbclassic``,
75-
the classic Notebook UI will be presented at the ``/tree`` path. As the
70+
When you choose to install only NbClassic via `pip install nbclassic`,
71+
the classic Notebook UI will be presented at the `/tree` path. As the
7672
other frontends are not installed, attempting to access the other paths
7773
will return errors. Note that NbClassic being a Jupyter Server extension,
7874
indicated Jupyter Server will be available. This provides an additional
79-
way to view the NbClassic frontend. You would be able to manually
75+
way to view the NbClassic frontend. You would be able to manually
8076
enable the extension when running an instance of Jupyter Server,
81-
``> jupyter server --ServerApp.jpserver_extensions="nbclassic=True"``,
82-
which will provide the NbClassic frontend at ``/tree`` path when visited.
77+
`> jupyter server --ServerApp.jpserver_extensions="nbclassic=True"`,
78+
which will provide the NbClassic frontend at `/tree` path when visited.
8379

84-
.. _JEP 79: https://jupyter.org/enhancement-proposals/79-notebook-v7/notebook-v7.html
85-
.. _team-compass note: https://github.com/jupyter/notebook-team-compass/issues/5#issuecomment-1085254000
80+
[jep 79]: https://jupyter.org/enhancement-proposals/79-notebook-v7/notebook-v7.html
81+
[team-compass note]: https://github.com/jupyter/notebook-team-compass/issues/5#issuecomment-1085254000

0 commit comments

Comments
 (0)