• Stars
    star
    2,204
  • Rank 20,932 (Top 0.5 %)
  • Language
    Python
  • License
    Other
  • Created over 12 years ago
  • Updated 3 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

nbconvert as a web service: Render Jupyter Notebooks as static web pages

Quick Run | GitHub Enterprise | Base URL | Local Development | Contributing | Extensions | Configuration | Security

Jupyter Notebook Viewer

Latest PyPI version TravisCI build status GitHub Gitter

Jupyter NBViewer is the web application behind The Jupyter Notebook Viewer, which is graciously hosted by OVHcloud and CDN services provided by fastly.

Run this locally to get most of the features of nbviewer on your own network.

If you need help using or installing Jupyter Notebook Viewer, please use the jupyter/help issue tracker. If you would like to propose an enhancement to nbviewer or file a bug report, please open an issue here, in the jupyter/nbviewer project.

Quick Run

If you have docker installed, you can pull and run the currently built version of the Docker container by

docker pull jupyter/nbviewer
docker run -p 8080:8080 jupyter/nbviewer

It automatically gets built with each push to master, so you'll always be able to get the freshest copy.

For speed and friendliness to GitHub, be sure to set GITHUB_OAUTH_KEY and GITHUB_OAUTH_SECRET:

docker run -p 8080:8080 -e 'GITHUB_OAUTH_KEY=YOURKEY' \
                          -e 'GITHUB_OAUTH_SECRET=YOURSECRET' \
                          jupyter/nbviewer

Or to use your GitHub personal access token, you can just set GITHUB_API_TOKEN.

GitHub Enterprise

To use nbviewer on your own GitHub Enterprise instance you need to set GITHUB_API_URL. The relevant API endpoints for GitHub Enterprise are prefixed with http://hostname/api/v3. You must also specify your OAUTH or API_TOKEN as explained above. For example:

docker run -p 8080:8080 -e 'GITHUB_OAUTH_KEY=YOURKEY' \
                          -e 'GITHUB_OAUTH_SECRET=YOURSECRET' \
                          -e 'GITHUB_API_URL=https://ghe.example.com/api/v3/' \
                          jupyter/nbviewer

With this configured all GitHub API requests will go to your Enterprise instance so you can view all of your internal notebooks.

Base URL

If the environment variable JUPYTERHUB_SERVICE_PREFIX is specified, then NBViewer always uses the value of this environment variable as the base URL.

In the case that there is no value for JUPYTERHUB_SERVICE_PREFIX, then as a backup the value of the --base-url flag passed to the python -m nbviewer command on the command line will be used as the base URL.

Local Development

With Docker

You can build a docker image that uses your local branch.

Build

cd <path to repo>
docker build -t nbviewer .

Run

cd <path to repo>
docker run -p 8080:8080 nbviewer

With Docker Compose

The Notebook Viewer uses memcached in production. To locally try out this setup, a docker-compose configuration is provided to easily start/stop the nbviewer and memcached containers together from your current branch. You will need to install docker prior to this.

Run

cd <path to repo>
pip install docker-compose
docker-compose up

Local Installation

The Notebook Viewer requires several binary packages to be installed on your system. The primary ones are libmemcached-dev libcurl4-openssl-dev pandoc libevent-dev libgnutls28-dev. Package names may differ on your system, see salt-states for more details.

If they are installed, you can install the required Python packages via pip.

$ cd <path to repo>
$ pip install -r requirements.txt

Static Assets

Static assets are maintained with bower and less (which require having npm installed), and the invoke python module.

$ cd <path to repo>
$ pip install -r requirements-dev.txt
$ npm install
$ invoke bower
$ invoke less [-d]

This will download the relevant assets into nbviewer/static/components and create the built assets in nbviewer/static/build.

Pass -d or --debug to invoke less to create a CSS sourcemap, useful for debugging.

Running Locally

$ cd <path to repo>
$ python -m nbviewer --debug --no-cache --host=127.0.0.1

This will automatically relaunch the server if a change is detected on a python file, and not cache any results. You can then just do the modifications you like to the source code and/or the templates then refresh the pages.

Contributing

If you would like to contribute to the project, please read the CONTRIBUTING.md. The CONTRIBUTING.md file explains how to set up a development installation and how to run the test suite.

Extending the Notebook Viewer

Providers

Providers are sources of notebooks and directories of notebooks and directories.

nbviewer ships with several providers

  • url
  • gist
  • github
  • huggingface
  • local

Writing a new Provider

There are already several providers proposed/requested. Some providers are more involved than others, and some, such as those which would require user authentication, will take some work to support properly.

A provider is implemented as a python module, which can expose a few functions:

uri_rewrites

If you just need to rewrite URLs (or URIs) of another site/namespace, implement uri_rewrites, which will allow the front page to transform an arbitrary string (usually an URI fragment), escape it correctly, and turn it into a "canonical" nbviewer URL. See the dropbox provider for a simple example of rewriting URLs without using a custom API client.

default_handlers

If you need custom logic, such as connecting to an API, implement default_handlers. See the github provider for a complex example of providing multiple handlers.

Error Handling

While you could re-implement upstream HTTP error handling, a small convenience method is provided for intercepting HTTP errors. On a given URL handler that inherits from BaseHandler, overload the client_error_message and re-call it with your message (or None). See the gist provider for an example of customizing the error message.

Formats

Formats are ways to present notebooks to the user.

nbviewer ships with three providers:

  • html
  • slides
  • script

Writing a new Format

If you'd like to write a new format, open a ticket, or speak up on gitter! We have some work yet to do to support your next big thing in notebook publishing, and we'd love to hear from you.

Config File and Command Line Configuration

NBViewer is configurable using a config file, by default called nbviewer_config.py. You can modify the name and location of the config file that NBViewer looks for using the --config-file command line flag. (The location is always a relative path, i.e. relative to where the command python -m nbviewer is run, and never an absolute path.)

If you don't know which attributes of NBViewer you can configure using the config file, run python -m nbviewer --generate-config (or python -m nbviewer --generate-config --config-file="my_custom_name.py") to write a default config file which has all of the configurable options commented out and set to their default values. To change a configurable option to a new value, uncomment the corresponding line and change the default value to the new value.

You can also run python -m nbviewer --help-all to see all of the configurable options. This is a more comprehensive version of python -m nbviewer --help, which gives a list of the most common ones along with flags and aliases you can use to set their values temporarily via the command line.

The config file uses the standard configuration syntax for Jupyter projects. For example, to configure the default port used to be 9000, add the line c.NBViewer.port = 9000 to the config file. If you want to do this just once, you can also run python -m nbviewer --NBViewer.port=9000 at the command line. (NBViewer.port also has the alias port, making it also possible to do, in this specific case, python -m nbviewer --port=9000. However not all configurable options have shorthand aliases like this; you can check using the outputs of python -m nbviewer --help and python -m nbviewer --help-all to see which ones do and which ones don't.)

One thing this allows you to do, for example, is to write your custom implementations of any of the standard page rendering handlers included in NBViewer, e.g. by subclassing the original handlers to include custom logic along with custom output possibilities, and then have these custom handlers always loaded by default, by modifying the corresponding lines in the config file. This is effectively another way to extend NBViewer.

Securing the Notebook Viewer

You can run the viewer as a JupyterHub 0.7+ service. Running the viewer as a service prevents users who have not authenticated with the Hub from accessing the nbviewer instance. This setup can be useful for protecting access to local notebooks rendered with the --localfiles option.

Add an entry like the following to your jupyterhub_config.py to have it start nbviewer as a managed service:

c.JupyterHub.services = [
    {
        # the /services/<name> path for accessing the notebook viewer
        'name': 'nbviewer',
        # the interface and port nbviewer will use
        'url': 'http://127.0.0.1:9000',
        # the path to nbviewer repo
        'cwd': '<path to repo>',
        # command to start the nbviewer
        'command': ['python', '-m', 'nbviewer']
    }
]

The nbviewer instance will automatically read the various JUPYTERHUB_* environment variables and configure itself accordingly. You can also run the nbviewer instance as an externally managed JupyterHub service, but must set the requisite environment variables yourself.

More Repositories

1

jupyter

Jupyter metapackage for installation, docs and chat
Python
14,886
star
2

notebook

Jupyter Interactive Notebook
Jupyter Notebook
11,528
star
3

docker-stacks

Ready-to-run Docker images containing Jupyter applications
Python
7,890
star
4

nbdime

Tools for diffing and merging of Jupyter notebooks.
TypeScript
2,649
star
5

nbconvert

Jupyter Notebook Conversion
Python
1,707
star
6

nbgrader

A system for assigning and grading notebooks
Python
1,274
star
7

dashboards

[RETIRED] See Voilà as a supported replacement
Jupyter Notebook
984
star
8

colaboratory

[deprecated] Jupyter CoLaboratory, goto google colab now
JavaScript
740
star
9

tmpnb

Creates temporary Jupyter Notebook servers using Docker containers. [DEPRECATED - See BinderHub project]
JavaScript
528
star
10

jupyter-drive

Google drive for jupyter notebooks
TypeScript
418
star
11

qtconsole

Jupyter Qt Console
Python
407
star
12

jupyter_client

Jupyter protocol client APIs
Python
379
star
13

terminado

Terminals served by tornado websockets
Python
366
star
14

atom-notebook

[Deprecated] Jupyter Notebook, but inside Atom.
JavaScript
306
star
15

help

✨ Need some help or have some questions? Please visit our Discourse page.
291
star
16

nbformat

Reference implementation of the Jupyter Notebook format
Python
259
star
17

jupyter_console

Jupyter Terminal Console
Python
249
star
18

jupyter_core

Core Jupyter functionality
Python
195
star
19

docker-notebook

Docker containers for the IPython notebook (+SciPy Stack)
Shell
188
star
20

jupyter-sphinx

Sphinx extension for rendering of Jupyter interactive widgets.
Python
186
star
21

dashboards_server

[RETIRED] Server that runs and renders Jupyter notebooks as interactive dashboards
JavaScript
181
star
22

jupyter.github.io

Project Jupyter's home on the World Wide Web
HTML
177
star
23

nbconvert-examples

Examples that illustrate how nbconvert can be used
Jupyter Notebook
164
star
24

kernel_gateway_demos

Demos associated with the kernel gateway incubator project
Jupyter Notebook
152
star
25

nbclient

A client library for executing notebooks. Formally nbconvert's ExecutePreprocessor
Python
149
star
26

declarativewidgets

[RETIRED] Jupyter Declarative Widget Extension
HTML
120
star
27

enhancement-proposals

Enhancement proposals for the Jupyter Ecosystem
Python
115
star
28

papyri

Python
84
star
29

roadmap

Master roadmap for Project Jupyter
84
star
30

governance

The governance process and model for Project Jupyter
Python
82
star
31

design

Design related materials for Project Jupyter
HTML
80
star
32

dashboards_bundlers

[RETIRED] Converts a notebook to a dashboard and deploys it / downloads it
Python
79
star
33

docker-demo-images

Demo images for use in try.jupyter.org and tmpnb.org
Jupyter Notebook
75
star
34

scipy-advanced-tutorial

Advance Tutorial For SciPy
JavaScript
75
star
35

nbclassic

Jupyter Notebook as a Jupyter Server extension
JavaScript
74
star
36

nb2kg

Python
73
star
37

services

This repository is deprecated. It has been moved to https://github.com/jupyterlab/jupyterlab as a sub-package
TypeScript
70
star
38

accessibility

A repository for ongoing work around making Jupyter's software accessible and inclusive
Python
65
star
39

jupyter_kernel_test

A tool for testing Jupyter kernels
Python
62
star
40

jupyter-packaging

Tools to help build and install Jupyter Python packages
Python
62
star
41

nbmanager

View and stop running IPython notebook servers
Python
51
star
42

telemetry

Configurable event-logging for Jupyter applications and extensions.
Python
50
star
43

ngcm-tutorial

Materials for the IPython/Jupyter workshop at the NGCM Summer Academy, at Southampton University, Boldrewood campus.
Jupyter Notebook
46
star
44

jupyter-js-notebook

JupyterLab notebook
TypeScript
46
star
45

debugger

Research and explorations for an interactive debugger for Jupyter
41
star
46

echo_kernel

A simple example kernel for Jupyter
Python
39
star
47

ipython-py3k

**DO NOT USE THIS REPOSITORY AT ALL** This repo has been merged into the main IPython one that now contains Python 3 support. This is kept only as a reference to developers.
Python
34
star
48

jsplugins

JavaScript Plugins for the IPython Notebook
32
star
49

jupyterhub-2016-workshop

Materials for an online mini-workshop around JupyterHub use cases, held July 22nd, 2016
31
star
50

dashboards_setup

[RETIRED] Recipes for setting up components related to the incubating dashboards effort
Jupyter Notebook
28
star
51

testpath

Test utilities for Python code working with files and commands
Python
27
star
52

strata-sv-2015-tutorial

Strata Silicon Valley 2015 Tutorial
Python
24
star
53

jupyter-js-plugins

TypeScript
23
star
54

surveys

Surveys and datasets collected by Project Jupyter
Jupyter Notebook
23
star
55

jupyter-sphinx-theme

A Sphinx theme for Jupyter and IPython documentation
HTML
22
star
56

jvm-repr

API for converting JVM objects to representations by MIME type, for the Jupyter ecosystem.
Java
22
star
57

notebook-research

Research on the usage of Jupyter notebooks
Jupyter Notebook
20
star
58

security

19
star
59

tutorial-dashboards-declarativewidgets

Materials for the PyData Carolinas 2016 tutorial, Turning Jupyter Notebooks into Data Applications
Jupyter Notebook
19
star
60

tmpnb-deploy

Deploying tmpnb nodes
Python
18
star
61

jupyterlab_json

This repository is deprecated. The extension has moved to https://github.com/jupyterlab/jupyter-renderers
JavaScript
16
star
62

kernels

Kernel testing and listing infrastructure
Python
16
star
63

mozfest15-training

Notebooks for Jupyter training session at Mozfest 2015
Jupyter Notebook
13
star
64

newsletter

A repo for collecting content for the Jupyter Newsletter
Jupyter Notebook
13
star
65

jupyterlab_geojson

This repository is deprecated. The extension has moved to https://github.com/jupyterlab/jupyter-renderers
JavaScript
13
star
66

tmpnb-redirector

Simple HTTP redirector for tmpnb nodes
Python
12
star
67

nature-demo

Materials for the November 2014 Nature Article
Jupyter Notebook
12
star
68

extension-builder

This repository is deprecated.
TypeScript
12
star
69

jupyter_events

Configurable event system for Jupyter applications and extensions.
Python
11
star
70

phosphor-notebook

Phosphor-based jupyter notebook
TypeScript
11
star
71

ipython-components

third-party javascript dependencies of IPython
JavaScript
11
star
72

try.jupyter.org

Try Jupyter!
HTML
10
star
73

jupyter-js-ui

TypeScript
10
star
74

jupyter-js-output-area

DEPRECATED: Javascript APIs for Jupyter output areas
TypeScript
10
star
75

cookiecutter-docker-stacks

Cookiecutter for community-maintained Jupyter Docker images
Python
10
star
76

ideas

A place for the Jupyter community to connect on ideas
9
star
77

kernel_gateway_bundlers

Converts a notebook to a kernel gateway microservice bundle for download
Python
8
star
78

jupyter_markdown

Documentation and tests related to Jupyter's Markdown syntax
Jupyter Notebook
8
star
79

try-jupyter

A JupyterLite deployment to try JupyterLab, Jupyter Notebook and IPython in the browser
Jupyter Notebook
8
star
80

talks

A collection of talks about Jupyter and IPython projects
Jupyter Notebook
8
star
81

jvm-magics

A plugin system for magic function implementations across JVM kernels.
Java
7
star
82

cdn.jupyter.org

Assets and layout for cdn.jupyter.org
Python
7
star
83

jupyter-js-utils

JavaScript utilities for the Jupyter frontend
TypeScript
6
star
84

jupyter_logger

Allows you to log Jupyter notebook user events anonymously.
TypeScript
6
star
85

jupyter-js-filebrowser

DEPRECATED: This code was copied into https://github.com/jupyter/jupyter-js-ui
TypeScript
5
star
86

notebook_shim

A shim layer for notebook traits and config
Python
5
star
87

jupyter-sprints

Resources for running a sprint
HTML
5
star
88

nbcache

Notebook Caching layer in Docker
5
star
89

docs-team-compass

Documentation Work Group Discussions
HTML
5
star
90

jupyter-js-input-area

DEPRECATED: Javascript APIs for Jupyter input areas
TypeScript
5
star
91

sphinxcontrib_github_alt

Github roles for Sphinx docs
Python
5
star
92

jupyterhub-carina

[RETIRED] JupyterHub integration with Carina
Python
5
star
93

win-tornado-terminals

Windows terminal backend for tornado
Python
5
star
94

jupyterlab-fasta

DEPRECATED: Moved to https://github.com/jupyterlab/jupyter-renderers. A JupyterLab Fasta viewer
TypeScript
5
star
95

spreadsheet

A spreadsheet component for phosphor
JavaScript
5
star
96

jupyter-js-editor

DEPRECATED: This code was copied into https://github.com/jupyter/jupyter-js-notebook
TypeScript
4
star
97

jupyter-communitycalls

📣 Resources for planning and hosting the Jupyter Community Calls
4
star
98

distinguished-contributors

Jupyter Distinguished Contributors
4
star
99

project-mgt

4
star
100

showcase

[RETIRED] A spot to try demos of one or more incubating Jupyter projects in Binder
Makefile
4
star