Skip to content

Commit 47d7d28

Browse files
ZsailerZsailer
committed
[wip] more docs
1 parent 5909660 commit 47d7d28

File tree

11 files changed

+167
-30
lines changed

11 files changed

+167
-30
lines changed

‎docs/source/contributing.rst renamed to ‎docs/source/contributors/contributing.rst

File renamed without changes.

‎docs/source/extension-authors/dependency.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
Jupyter Server as a dependency
2+
==============================
3+

‎docs/source/frontends.rst renamed to ‎docs/source/extension-authors/frontends.rst

File renamed without changes.

‎docs/source/faq.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
Frequently asked questions
2+
==========================
3+
4+
Can I configure multiple extensions at once?
5+
--------------------------------------------

‎docs/source/index.rst

Lines changed: 24 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -2,18 +2,18 @@
22
Jupyter Server
33
==============
44

5-
Jupyter Server is the backend—the core services, APIs, and `REST endpoints`_—to most Jupyter applications.
5+
Jupyter Server is the backend—the core services, APIs, and `REST endpoints`_—to Jupyter applications.
66

77
.. note::
88

9-
This project replaces the Tornado Server in previous versions of the `Jupyter Notebook`_ project. Before the Jupyter Server project, the `Jupyter Notebook`_ came with it's own Tornado Web Server. As a consequence, other Jupyter frontends had to depend on Jupyter Notebook (and all of its Javascript code) to get a working Jupyter Server. This project provides Jupyter Server without a default frontend and views all frontends—including the `Jupyter Notebook`_—as equal and separate.
9+
This project replaces the Tornado Web Server in the `Jupyter Notebook`_. Previously, Jupyter applications depended on Jupyter Notebook's server (and thus, got all of its Javascript code). Jupyter Server comes without a default frontend and views all frontends—including the `Jupyter Notebook`_—as equal and separate. For help on migrating from Notebook Server to Jupyter Server, see `this page <operators/migrate-from-nbserver>`_.
1010

1111
.. _Tornado: https://www.tornadoweb.org/en/stable/
1212
.. _Jupyter Notebook: https://github.com/jupyter/notebook
1313
.. _REST endpoints: http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml
1414

1515

16-
The Jupyter Server is a highly technical piece of the Jupyter Stack. Most users won't touch this library directly, so the documentation will be different for different types of personas. To help you navigate the docs, we've separated the documentation for different personas:
16+
The Jupyter Server is a highly technical piece of the Jupyter Stack. Since most users won't import this library directly, we broke the documentation into separate personas:
1717

1818
1. :ref:`Users <users>`: people using Jupyter applications
1919
2. Operators: people deploying or serving Jupyter applications to others.
@@ -22,38 +22,40 @@ The Jupyter Server is a highly technical piece of the Jupyter Stack. Most users
2222

2323
.. toctree::
2424
:caption: Users
25-
:maxdepth: 2
25+
:maxdepth: 1
2626
:name: users
27-
:titlesonly:
2827

2928
users/installation
3029
users/configuration
3130
users/launching
3231
users/help
3332

34-
Operators
35-
~~~~~~~~~
36-
37-
- Serving a Jupyter Server with multiple frontends.
38-
- Running an extension from its own endpoint
39-
- Running a serve with multiple frontends
40-
-
41-
- Managing multiple extensions.
42-
- Listing all extensions.
43-
- Enabling/disabling extensions
44-
- If something goes wrong.
45-
- Configuring extensions.
46-
- Extension config directory structure
47-
- Changelog
33+
.. toctree::
34+
:caption: Operators
35+
:maxdepth: 1
36+
:name: operators
37+
38+
operators/multiple-frontends
39+
operators/configuring-extensions
40+
operators/migrate-from-nbserver
41+
operators/public-server
42+
operators/security
43+
44+
.. toctree::
45+
:caption: Extension Authors
46+
:maxdepth: 1
47+
:name: extension-authors
48+
49+
extension-authors/dependency
50+
extension-authors/frontends
51+
4852

49-
Extension Authors
50-
~~~~~~~~~~~~~~~~~
5153

5254
- Depending on Jupyter Server
5355
- Migrating a Notebook server extension to Jupyter Server
5456
- Writing a basic server extension from scratch
5557
- Writing a frontend server extension from scratch
56-
- Changelog
58+
5759

5860
Contributors
5961
~~~~~~~~~~~~

‎docs/source/operators/configuring-extensions.rst

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
Configuring Extensions
2+
======================
3+
4+
Some Jupyter Server extensions are also configurable applications. There are two ways to configure such extensions: i) pass arguments to the extension's entry point or ii) list configurable options in a Jupyter config file.
5+
6+
Jupyter Server looks for an extension's config file in a set of specific paths. Use the ``jupyter`` entry point to list these paths:
7+
8+
.. code-block:: console
9+
10+
> jupyter --paths
11+
12+
config:
13+
/Users/username/.jupyter
14+
/usr/local/etc/jupyter
15+
/etc/jupyter
16+
data:
17+
/Users/username/Library/Jupyter
18+
/usr/local/share/jupyter
19+
/usr/share/jupyter
20+
runtime:
21+
/Users/username/Library/Jupyter/runtime
22+
23+
24+
Extension config from file
25+
--------------------------
26+
27+
Jupyter Server expects the file to be named after the extension's name like so: ``jupyter_{extension_name}_config``. For example, the Jupyter Notebook's config file is ``jupyter_notebook_config``.
28+
29+
Configuration files can be Python or JSON files.
30+
31+
In Python config files, each trait will be prefixed with ``c.`` that links the trait to the config loader. For example, Jupyter Notebook config might look like:
32+
33+
.. code-block:: python
34+
35+
# jupyter_notebook_config.py
36+
37+
c.NotebookApp.port = 9999
38+
39+
40+
A Jupyter Server can automatically load config for multiple enabled extensions.
41+
42+
43+
44+
45+
Extension config on the command line
46+
------------------------------------
47+

‎docs/source/operators/managing-extensions.rst

Whitespace-only changes.

‎docs/source/migrate_from_notebook.rst renamed to ‎docs/source/operators/migrate-from-nbserver.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
.. _migrate_from_notebook:
22

3-
Migrate from Notebook
4-
=====================
3+
Migrating from Notebook Server
4+
==============================
55

66
To migrate from notebook server to plain jupyter server, follow these steps:
77

‎docs/source/operators/multiple-frontends.rst

Lines changed: 84 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,86 @@
1-
Serving a Jupyter Server with multiple frontends
2-
================================================
1+
Managing multiple extensions
2+
----------------------------
33

4-
One of the major benefits of Jupyter Server is that you can run serve multiple Jupyter frontend applications on top of the same server.
4+
One of the major benefits of Jupyter Server is that you can run serve multiple Jupyter frontend applications above the same Tornado web server. That's because every Jupyter frontend application is now a server extension. When you run a Jupyter Server will multiple extensions enabled, each extension appends its own set of handlers and static assets to the server.
55

6-
Each Jupyter frontend application *should* be a Jupyter Server extension. When you install these extensions,
6+
Listing extensions
7+
~~~~~~~~~~~~~~~~~~
8+
9+
When you install a Jupyter Server extension, it *should* automatically add itself to your list of enabled extensions. You can see a list of installed extensions by calling:
10+
11+
.. code-block:: console
12+
13+
> jupyter server extension list
14+
15+
config dir: /Users/username/etc/jupyter
16+
myextension enabled
17+
- Validating myextension...
18+
myextension OK
19+
20+
Enabling/disabling extensions
21+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
22+
23+
You enable/disable an extension using the following commands:
24+
25+
.. code-block:: console
26+
27+
> jupyter server extension enable myextension
28+
29+
Enabling: myextension
30+
- Validating myextension...
31+
myextension OK
32+
- Extension successfully enabled.
33+
34+
35+
> jupyter server extension disable myextension
36+
37+
Disabling: jupyter_home
38+
- Validating jupyter_home...
39+
jupyter_home OK
40+
- Extension successfully disabled.
41+
42+
43+
Running an extensions from its entrypoint
44+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
45+
46+
Extensions that are also Jupyter applications (i.e. Notebook, JupyterLab, Voila, etc.) can be launched
47+
from a CLI entrypoint. For example, launch Jupyter Notebook using:
48+
49+
.. code-block:: console
50+
51+
> jupyter notebook
52+
53+
54+
Jupyter Server will automatically start a server and the browser will be routed to Jupyter Notebook's default URL (typically, ``/tree``).
55+
56+
Other enabled extension will still be available to the user. The entrypoint simply offers a more direct (backwards compatible) launching mechanism.
57+
58+
Launching a server with multiple extensions
59+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
60+
61+
If multiple extensions are enabled, a Jupyter Server can be launched directly:
62+
63+
.. code-block:: console
64+
65+
> jupyter server
66+
67+
[I 2020-03-23 15:44:53.290 ServerApp] Serving notebooks from local directory: /Users/username/path
68+
[I 2020-03-23 15:44:53.290 ServerApp] Jupyter Server 0.3.0.dev is running at:
69+
[I 2020-03-23 15:44:53.290 ServerApp] http://localhost:8888/?token=<...>
70+
[I 2020-03-23 15:44:53.290 ServerApp] or http://127.0.0.1:8888/?token=<...>
71+
[I 2020-03-23 15:44:53.290 ServerApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation).
72+
[I 2020-03-23 15:44:53.290 ServerApp] Welcome to Project Jupyter! Explore the various tools available and their corresponding documentation. If you are interested in contributing to the platform, please visit the communityresources section at https://jupyter.org/community.html.
73+
[C 2020-03-23 15:44:53.296 ServerApp]
74+
75+
To access the server, open this file in a browser:
76+
file:///Users/username/pathjpserver-####-open.html
77+
Or copy and paste one of these URLs:
78+
http://localhost:8888/?token=<...>
79+
or http://127.0.0.1:8888/?token=<...>
80+
81+
82+
Extensions can also be enabled manually from the Jupyter Server entrypoint using the ``jpserver_extensions`` trait:
83+
84+
.. code-block:: console
85+
86+
> jupyter server --ServerApp.jpserver_extensions='{"myextension":{"enabled": True}}'

‎docs/source/public_server.rst renamed to ‎docs/source/operators/public-server.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
.. _working_remotely:
22

3-
Running a Jupyter server
4-
========================
3+
Running a public Jupyter Server
4+
===============================
55

66

77
The Jupyter Server's web application is based on a

‎docs/source/security.rst renamed to ‎docs/source/operators/security.rst

File renamed without changes.

0 commit comments

Comments
 (0)