Quick Run |
GitHub Enterprise |
Base URL |
Local Development |
Contributing |
Extensions |
Configuration |
Security
Jupyter Notebook Viewer
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
urlgistgithubhuggingfacelocal
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:
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.
