Skip to content

Commit

Permalink
Merge pull request #53 from choldgraf/website
Browse files Browse the repository at this point in the history 
Minimal steps to add a website
  • Loading branch information
@blink1073
blink1073 authored Jun 15, 2020
2 parents 0739b61 + 3b2ba4f commit 0c62e06
Show file tree
Hide file tree
Showing 16 changed files with 205 additions and 81 deletions.
37 changes: 37 additions & 0 deletions .circleci/config.yml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
version: 2
jobs:
build_docs:
docker:
- image: circleci/python:3.6-stretch
steps:
# Get our data and merge with upstream
- run: sudo apt-get update
- checkout

- restore_cache:
keys:
- cache-pip

- run: |
pip install jupyter-book
- save_cache:
key: cache-pip
paths:
- ~/.cache/pip

# Build the docs
- run:
name: Build docs to store
command: |
jb build .
- store_artifacts:
path: _build/html/
destination: html


workflows:
version: 2
default:
jobs:
- build_docs
37 changes: 37 additions & 0 deletions .github/workflows/docs.yml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
name: deploy-book

# Only run this when the master branch changes
on:
push:
branches:
- master

# This job installs dependencies, build the book, and pushes it to `gh-pages`
jobs:
deploy-book:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2

# Install dependencies
- name: Set up Python 3.7
uses: actions/setup-python@v1
with:
python-version: 3.7

- name: Install dependencies
run: |
pip install -U jupyter-book
# Build the book
- name: Build the book
run: |
jupyter-book build .
# Push the book's HTML to github-pages
- name: GitHub Pages action
uses: peaceiris/actions-gh-pages@v3.5.9
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./_build/html
3 changes: 3 additions & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,3 +25,6 @@ build/Release
# Dependency directory
# https://www.npmjs.org/doc/misc/npm-faq.html#should-i-check-my-node_modules-folder-into-git
node_modules

# Jupyter Book
_build
84 changes: 42 additions & 42 deletions jupyter-server/jupyter-server.md → 28-jupyter-server/jupyter-server.md
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,13 @@
# Standalone Jupyter server enhancement proposal [active]

| Item | Value |
|------------|------------------------------------------------------------------------------------------------------------------------------|
| JEP Number | 10 |
| Title | Standalone Jupyter Server |
| Authors | Zach Sailer ([@Zsailer](https://github.com/Zsailer)) and Sylvain Corlay ([@SylvainCorlay](https://github.com/sylvaincorlay)) |
| Status | Draft |
| Type | S - [Standards Track](https://www.python.org/dev/peps/#pep-types-key) JEP |
| Created | 20 September 2016 |
| History | 20 September 2016, 12 February 2019 |
---
title: Standalone Jupyter server
authors: Zach Sailer ([@Zsailer](https://github.com/Zsailer)) and Sylvain Corlay ([@SylvainCorlay](https://github.com/sylvaincorlay))
issue-number: 31
pr-number: 28
date-started: "2016-09-20"
type: S - [Standards Track](https://www.python.org/dev/peps/#pep-types-key)
---

# Standalone Jupyter server enhancement

## Problem

Expand All @@ -19,7 +18,7 @@ There are now multiple frontends that talk to the backend services provided by t
Decouple the backend server (and its configuration) from the classic notebook frontend. This will require the following steps:

1. [Separate `jupyter_server` repository](#separate-jupyter_server-repository)
- A fork of the `notebook` repository.
- A fork of the `notebook` repository.
- Pure Python package with notebook backend services.
- `notebook` tornado handlers and frontend logic stay in `notebook` repo.
- Deprecated notebook server APIs do not move to `jupyter_server`.
Expand All @@ -29,12 +28,12 @@ Decouple the backend server (and its configuration) from the classic notebook fr
1. [Extensions as Applications](#extensions-as-applications)
- server extensions move to `jupyter_server`.
- New `ExtensionApp` class
- Notebook, jupyterlab, etc. become ExtensionApps.
- Notebook, jupyterlab, etc. become ExtensionApps.
1. [New server extensions mechanism.](#new-server-extensions-mechanism)
- new base classes to create applications from server extensions.
- nbextensions stay in `notebook`.
- new base classes to create applications from server extensions.
- nbextensions stay in `notebook`.
- `jupyter_notebook_config.d` folder becomes `jupyter_server_config.d`
1. [Namespacing static files and REST API urls.](#add-namespacing-to-static-endpoints-and-rest-api-urls)
1. [Namespacing static files and REST API urls.](#add-namespacing-to-static-endpoints-and-rest-api-urls)
- Each extension serves static files at the `/static/<extension>` url.
- New `ExtensionHandlerApp` class
1. [Configuration System](#configuration-system)
Expand All @@ -45,7 +44,7 @@ Decouple the backend server (and its configuration) from the classic notebook fr
### Separate `jupyter_server` repository

The first thing to do is fork `notebook`. A new `jupyter_server` repo will keep the server specific logic and remove:
1. the notebook frontend code,
1. the notebook frontend code,
2. deprecated notebook server APIs, and
3. tornado handlers to the classic notebook interface. These pieces will stay in the `notebook` repository.

Expand Down Expand Up @@ -74,11 +73,11 @@ Preliminary work resides in [jupyter_server](https://github.com/jupyter/jupyter_

The server-notebook split is an opportunity to clearly define Jupyter's core services. The old notebook server was comprised of many services, and it could be extended by separate "server extensions". However, it isn't clear what should be a core service versus a server extension. Some extensions were "grand-fathered" in as core services to make the notebook application more full-featured (e.g. nbconvert, terminals, contents, ...). Now that we are separating the server from the classic notebook, we need to reevaluate what services are core to the Jupyter Server.

Jupyter server aims to be a core building block for other applications (like nteract, lab, dashboards, standalone widgets, etc.). To achieve this, we need to define the simplest "unit" that defines a Jupyter Server: `kernels`, `kernelspec`, and `sessions`. Other services become extensions to the core server (using the `load_jupyter_server_extension` mechanism defined below).
Jupyter server aims to be a core building block for other applications (like nteract, lab, dashboards, standalone widgets, etc.). To achieve this, we need to define the simplest "unit" that defines a Jupyter Server: `kernels`, `kernelspec`, and `sessions`. Other services become extensions to the core server (using the `load_jupyter_server_extension` mechanism defined below).

### Extensions as Applications

A new `ExtensionApp` class will be available in `jupyter_server.extensions.extensionapp`. It enables developers to make server extensions behave like standalone Jupyter applications. Jupyterlab is an example of this kind of server extension. It can be configured, initialized, and launched from the command line. When Lab is launched, it first initializes and configures a jupyter (notebook) server, then loads the configured jupyterlab extension and redirects the use to the Lab landing page.
A new `ExtensionApp` class will be available in `jupyter_server.extensions.extensionapp`. It enables developers to make server extensions behave like standalone Jupyter applications. Jupyterlab is an example of this kind of server extension. It can be configured, initialized, and launched from the command line. When Lab is launched, it first initializes and configures a jupyter (notebook) server, then loads the configured jupyterlab extension and redirects the use to the Lab landing page.

`ExtensionApp` handles the boilerplate code to make Jupyter applications that configure and launch server extensions directly. It inherits `jupyter_core.JupyterApp` and exposes a command line entry point: `jupyter <extension-name>`. When an extension is launched, it first configures and starts a jupyter_server (`ServerApp`); then, it loads the configured extension and redirects users to the extension's landing page. Extension developers simply inherit the `ExtensionApp` and add the extension's `load_jupyter_server_extension` as a `staticmethod`.

Expand All @@ -93,7 +92,7 @@ class MyExtension(ExtensionApp):
load_jupyter_server_extension = staticmethod(load_jupyter_server_extension)
```

`ExtensionApp`s can be configured by `jupyter_<extension-name>_config.py|json` as well. When the server extension is loaded by a server or launched from the command line, it searches the list of `jupyter --paths` for configured traits in these files.
`ExtensionApp`s can be configured by `jupyter_<extension-name>_config.py|json` as well. When the server extension is loaded by a server or launched from the command line, it searches the list of `jupyter --paths` for configured traits in these files.

Initial experimental work resides in [`jupyter_server_extension`](https://github.com/Zsailer/jupyter_server_extension).

Expand All @@ -105,21 +104,21 @@ c.ServerApp.jpserver_extensions = {
'notebook': True
}
```
Users can also launch the notebook application using the (usual)`jupyter notebook` command line interface.
Users can also launch the notebook application using the (usual)`jupyter notebook` command line interface.

### New server extensions mechanism.

The new extension mechanism in the *jupyter server* will differ from notebook's server extensions.

* The `--sys-prefix` installation would become the default. (Users are confused when enabling an extension requires more permissions than the installation of the package). Installation in system-wide directories would be done with the `--system` option.
* The `--sys-prefix` installation would become the default. (Users are confused when enabling an extension requires more permissions than the installation of the package). Installation in system-wide directories would be done with the `--system` option.
* Installing an extension will include the addition of a 'manifest' file into a conf.d directory (under one of the Jupyter configuration directories, `user / sys-prefix / system`). The placement of such an extension manifest provided by a Python package can be done with `jupyter server extension install --py packagename [--user / --system / --sys-prefix]`. Packages (conda or wheels) carrying server extensions could place such manifests in the sys-prefix path by default effectively installing them. Development installations would also require the call to the installation command.

* Enabling an extension is separate from the installation. Multiple scenarios are possible:
- enabling an extension at the same level (user / sys-prefix / system) as where it was installed, or at a higher level (user for sys-prefix and system, or sys-prefix for system).
- forcibly disabling an extension that was enabled at a lower level of precedence.
- forcibly enabling an extension that was disabled at a lower level of precedence.
This would be done via two `conf.d` configuration directories managing a list of disabled extensions and list of enabled extensions in the form of empty files having the name of the corresponding extension. If an extension is both disabled and enabled at the same level of precedence, disabling has precedence. Packages (conda or wheels) could place such a enabler file in the sys-prefix path by default. The `jupyter server extension enable` command would be required for development installations.

(Possibly) when an extension is enabled at a given precedence level, it may only look for the version of the extension installed at the same or lower precedence level. For example, if an extension `foobar` is installed and enabled system wide, but a user installs a version with `--user`, this version will only be picked up if the user also enables it with `--user`.

### Add namespacing to `static` endpoints and REST API urls.
Expand All @@ -136,32 +135,32 @@ Preliminary experimental work resides in the [`jupyter_server_extension`](https:

Splitting the server-specific pieces from the classic notebook affects Jupyter's configuration system. This is a non-trivial problem. Changing Jupyter's configuration system affects everyone. We need to consider how to make this transition as painless as possible. At the end of this section, we list some steps that make reduce the friction.

Here is a list of things the changes on the configuration system:
Here is a list of things the changes on the configuration system:
* Move server-specific configuration from `jupyter_notebook_config.py|json` into `jupyter_server_config.py|json`.
* Notebook configuration will stay in `jupyter_notebook_config.py|json`.
* Server extensions configurations move from `jupyter_notebok_config.d` to `jupyter_server_config.d`.
* The tornado server and webapp configurable applications move to `jupyter_server`. They become `ServerApplication` and `ServerWebApp`
* The `NotebookApp` becomes a server extension. It would only load notebook specific configuration/traitlets, from `jupyter_notebook_config.py|json`.
* Server extensions are found using the `jpserver_extensions` trait instead of the `nbserver_extensions` trait in the `ServerApp`.
* Server extensions are found using the `jpserver_extensions` trait instead of the `nbserver_extensions` trait in the `ServerApp`.
* Extension configuration files in `jupyter_server_config.d` must be enabled using the `jpserver_extensions` trait. They are enabled by JSON config files in `jupyter_server_config.d`.
* Extensions can create their own configuration files in `{sys-prefix}/etc/jupyter/` or `~/.jupyter`, i.e. `jupyter_<my-extension>_config.py|json`.
* General `jupyter_config.py|json` files must update to set server-specific configuration using the `ServerApp` and notebook specific configuration using `NotebookApp`.

Some traits will stay in `jupyter_notebook_config.py|json`. Here is a list of those traits (everything else moves to server config files):
* extra_nbextensions_path
* enable_mathjax
* max_body_size
* max_buffer_size
* notebook_dir
* mathjax_url
* get_secure_cookie_kwargs
* mathjax_config
* extra_nbextensions_path
* enable_mathjax
* max_body_size
* max_buffer_size
* notebook_dir
* mathjax_url
* get_secure_cookie_kwargs
* mathjax_config
* ignore_minified_js

Here are some steps we can take to reduce the friction for transitioning:
* **Copy (not move)** `jupyter_notebook_config.py|json` to `jupyter_server_config.py|json`
* **Copy (not move)** `jupyter_notebook_config.d/` to `jupyter_server_config.d`.
* `NotebookApp` becomes `ServerApp` in all copied files.
* `NotebookApp` becomes `ServerApp` in all copied files.
* Leftover server traits in `jupyter_notebook_config.py|json` get ignored when the notebook extension is initialized. Server traits are only read from `jupyter_server_config.py|json`.
* Document like crazy!

Expand All @@ -173,17 +172,18 @@ To make migration easier on users, a `migrate` application will be available to

### How this effects other projects

[**Classic notebook**]()
**Classic notebook**
In short, the classic notebook will become a server extension application. The rest of this proposal describes the details behind what will change in the notebook repo.
[`JupyterServerExtensionApp`]().

[**Jupyter Lab**]()
`JupyterServerExtensionApp`

**Jupyter Lab**
Jupyter lab will also become a server extension application. The new classes described above should simplify the way JupyterLab interfaces with the server.

[**Kernel Gateway**]()
Kernel Gateway can use the new Jupyter Server to server kernels as a service. The new Jupyter server will remove the unwanted services that Kernel Gateway currently removes by using a custom server application. KG will also be able to swap out the kernels and kernelspec manager in the Jupyter Server with its custom classes.
**Kernel Gateway**
Kernel Gateway can use the new Jupyter Server to server kernels as a service. The new Jupyter server will remove the unwanted services that Kernel Gateway currently removes by using a custom server application. KG will also be able to swap out the kernels and kernelspec manager in the Jupyter Server with its custom classes.

[**Kernel Nanny**]()
**Kernel Nanny**

## Pros and Cons

Expand All @@ -198,7 +198,7 @@ Kernel Gateway can use the new Jupyter Server to server kernels as a service. Th

* Break the classic notebook in a backwards incompatible way.
* Affects many projects. The transition may be painful?
* Adding a dependency injection system adds new complexity.
* Adding a dependency injection system adds new complexity.

## Relevent Issues, PRs, and discussion

Expand All @@ -217,4 +217,4 @@ Static Namespace:

## Interested

@Zsailer, @SylvainCorlay, @ellisonbg, @blink1073, @kevin-bates
@Zsailer, @SylvainCorlay, @ellisonbg, @blink1073, @kevin-bates
24 changes: 13 additions & 11 deletions 29-jep-process/README.md → 29-jep-process/jep-process.md
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,16 @@
| Item | Value |
| ---------- | ------------------------------------------------------------ |
| JEP number | 29 |
| Title | Jupyter Enhancement Proposal |
| Authors | Jason Grout ([jason@jasongrout.org](mailto:jason@jasongrout.org)), Safia Abdalla ([safia@safia.rocks](mailto:safia@safia.rocks)), John Lam ([jflam@microsoft.com](mailto:jflam@microsoft.com)), Kevin M. McCormick ([mckev@amazon.com](mailto:mckev@amazon.com)), Pierre Brunelle ([brunep@amazon.com](mailto:brunep@amazon.com)), Paul Ivanov ([pi@berkeley.edu](mailto:pi@berkeley.edu)) |
| Status | Draft |
| Type | P - Process |
| Created | 23-Feb-2019 |
| History | 04-Mar-2019, 07-Mar-2019 |

### Background
---
title: Jupyter Enhancement Proposal
authors: |
Jason Grout ([jason@jasongrout.org](mailto:jason@jasongrout.org)), Safia Abdalla ([safia@safia.rocks](mailto:safia@safia.rocks)), John Lam ([jflam@microsoft.com](mailto:jflam@microsoft.com)), Kevin M. McCormick ([mckev@amazon.com](mailto:mckev@amazon.com)), Pierre Brunelle ([brunep@amazon.com](mailto:brunep@amazon.com)), Paul Ivanov ([pi@berkeley.edu](mailto:pi@berkeley.edu))
issue-number: 27
pr-number: 29
date-started: "2019-02-23"
type: P - Process
---

# Jupyter Enhancement Proposal

## Background

Project Jupyter has an existing repository and process for “Jupyter Enhancement Proposals” or JEP for short. The repository is here:

Expand Down
11 changes: 10 additions & 1 deletion voila-incorporation/voila-incorporation.md → ...oila-incorporation/voila-incorporation.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,13 @@
# Voilà Incorporation Proposal
---
title: Voilà Incorporation
authors: SylvainCorlay
issue-number: XX
pr-number: 42
date-started: "2019-10-14"
type: S - [Standards Track](https://www.python.org/dev/peps/#pep-types-key)
---

# Voilà Incorporation

## Problem

Expand Down
Loading

0 comments on commit 0c62e06

Please sign in to comment.