New nbextensions installation API

docs/source/examples/Notebook/Distributing Jupyter Extensions as Python Packages.ipynb

@@ -0,0 +1,280 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Distributing Jupyter Extensions as Python Packages"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Overview\n",
+    "### How can the notebook be extended?\n",
+    "The Jupyter Notebook client and server application are both deeply customizable. Their behavior can be extended by creating, respectively:\n",
+    "\n",
+    "- nbextension: a notebook extension\n",
+    "    - a single JS file, or directory of JavaScript, Cascading StyleSheets, etc. that contain at\n",
+    "      minimum a JavaScript module packaged as an\n",
+    "      [AMD modules](https://en.wikipedia.org/wiki/Asynchronous_module_definition)\n",
+    "      that exports a function `load_ipython_extension`\n",
+    "- server extension: an importable Python module\n",
+    "    - that implements `load_jupyter_server_extension`"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Why create a Python package for Jupyter extensions?\n",
+    "Since it is rare to have a server extension that does not have any frontend components (an nbextension), for convenience and consistency, all these client and server extensions with their assets can be packaged and versioned together as a Python package with a few simple commands. This makes installing the package of extensions easier and less error-prone for the user. "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Installation of Jupyter Extensions\n",
+    "### Install a Python package containing Jupyter Extensions\n",
+    "There are several ways that you may get a Python package containing Jupyter Extensions. Commonly, you will use a package manager for your system:\n",
+    "```shell\n",
+    "pip install helpful_package\n",
+    "# or\n",
+    "conda install helpful_package\n",
+    "# or\n",
+    "apt-get install helpful_package\n",
+    "\n",
+    "# where 'helpful_package' is a Python package containing one or more Jupyter Extensions\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Enable a Server Extension\n",
+    "\n",
+    "The simplest case would be to enable a server extension which has no frontend components. \n",
+    "\n",
+    "A `pip` user that wants their configuration stored in their home directory would type the following command:\n",
+    "```shell\n",
+    "jupyter serverextension enable --py helpful_package\n",
+    "```\n",
+    "\n",
+    "Alternatively, a `virtualenv` or `conda` user can pass `--sys-prefix` which keeps their environment isolated and reproducible. For example:\n",
+    "```shell\n",
+    "# Make sure that your virtualenv or conda environment is activated\n",
+    "[source] activate my-environment\n",
+    "\n",
+    "jupyter serverextension enable --py helpful_package --sys-prefix\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Install the nbextension assets"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "If a package also has an nbextension with frontend assets that must be available (but not neccessarily enabled by default), install these assets with the following command:\n",
+    "```shell\n",
+    "jupyter nbextension install --py helpful_package # or --sys-prefix if using virtualenv or conda\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Enable nbextension assets\n",
+    "If a package has assets that should be loaded every time a Jupyter app (e.g. lab, notebook, dashboard, terminal) is loaded in the browser, the following command can be used to enable the nbextension:\n",
+    "```shell\n",
+    "jupyter nbextension enable --py helpful_package # or --sys-prefix if using virtualenv or conda\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Did it work? Check by listing Jupyter Extensions.\n",
+    "After running one or more extension installation steps, you can list what is presently known about nbextensions or server extension. The following commands will list which extensions are available, whether they are enabled, and other extension details:\n",
+    "\n",
+    "```shell\n",
+    "jupyter nbextension list\n",
+    "jupyter serverextension list\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Additional resources on creating and distributing packages        \n",
+    "\n",
+    "> Of course, in addition to the files listed, there are number of other files one needs to build a proper package. Here are some good resources:\n",
+    "- [The Hitchhiker's Guide to Packaging](http://the-hitchhikers-guide-to-packaging.readthedocs.org/en/latest/quickstart.html)\n",
+    "- [Repository Structure and Python](http://www.kennethreitz.org/essays/repository-structure-and-python) by Kenneth Reitz\n",
+    "\n",
+    "> How you distribute them, too, is important:\n",
+    "- [Packaging and Distributing Projects](http://python-packaging-user-guide.readthedocs.org/en/latest/distributing/)\n",
+    "- [conda: Building packages](http://conda.pydata.org/docs/building/build.html)\n",
+    "\n",
+    "> Here are some tools to get you started:\n",
+    "- [generator-nbextension](https://github.com/Anaconda-Server/generator-nbextension)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Example - Server extension"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Creating a Python package with a server extension\n",
+    "\n",
+    "Here is an example of a python module which contains a server extension directly on itself. It has this directory structure:\n",
+    "```\n",
+    "- setup.py\n",
+    "- MANIFEST.in\n",
+    "- my_module/\n",
+    "  - __init__.py\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Defining the server extension\n",
+    "This example shows that the server extension and its `load_jupyter_server_extension` function are defined in the `__init__.py` file.\n",
+    "#### `my_module/__init__.py`\n",
+    "\n",
+    "```python\n",
+    "def _jupyter_server_extension_paths():\n",
+    "    return [{\n",
+    "        \"module\": \"my_module\"\n",
+    "    }]\n",
+    "\n",
+    "\n",
+    "def load_jupyter_server_extension(nbapp):\n",
+    "    nbapp.log.info(\"my module enabled!\")\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Install and enable the server extension\n",
+    "Which a user can install with:\n",
+    "```\n",
+    "jupyter serverextension enable --py my_module [--sys-prefix]\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Example - Server extension and nbextension"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Creating a Python package with a server extension and nbextension\n",
+    "Here is another server extension, with a front-end module.  It assumes this directory structure:\n",
+    "\n",
+    "```\n",
+    "- setup.py\n",
+    "- MANIFEST.in\n",
+    "- my_fancy_module/\n",
+    "  - __init__.py\n",
+    "  - static/\n",
+    "    index.js\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "collapsed": true
+   },
+   "source": [
+    "### Defining the server extension and nbextension\n",
+    "This example again shows that the server extension and its `load_jupyter_server_extension` function are defined in the `__init__.py` file. This time, there is also a function `_jupyter_nbextension_path` for the nbextension.\n",
+    "\n",
+    "#### `my_fancy_module/__init__.py`\n",
+    "\n",
+    "```python\n",
+    "def _jupyter_server_extension_paths():\n",
+    "    return [{\n",
+    "        \"module\": \"my_fancy_module\"\n",
+    "    }]\n",
+    "\n",
+    "# Jupyter Extension points\n",
+    "def _jupyter_nbextension_paths():\n",
+    "    return [dict(\n",
+    "        section=\"notebook\",\n",
+    "        # the path is relative to the `my_fancy_module` directory\n",
+    "        src=\"static\",\n",
+    "        # directory in the `nbextension/` namespace\n",
+    "        dest=\"my_fancy_module\",\n",
+    "        # _also_ in the `nbextension/` namespace\n",
+    "        require=\"my_fancy_module/index\")]\n",
+    "\n",
+    "def load_jupyter_server_extension(nbapp):\n",
+    "    nbapp.log.info(\"my module enabled!\")\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Install and enable the server extension and nbextension\n",
+    "\n",
+    "The user can install and enable the extensions with the following set of commands:\n",
+    "```\n",
+    "jupyter nbextension install --py my_fancy_module [--sys-prefix|--user]\n",
+    "jupyter nbextension enable --py my_fancy_module [--sys-prefix|--system]\n",
+    "jupyter serverextension enable --py my_fancy_module [--sys-prefix|--system]\n",
+    "```"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.5.1"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 0
+}

docs/source/extending/frontend_extensions.rst

@@ -202,10 +202,12 @@ the prefix. For the action name, the following guidelines should be considered:
 Installing and enabling extensions
 ----------------------------------
 
-You can install your nbextension with the command:
+You can install your nbextension with the command::
 
-    jupyter nbextension install path/to/my_extension/
+    jupyter nbextension install path/to/my_extension/ [--user|--sys-prefix]
 
+The default installation is system-wide. You can use ``--user`` to do a per-user installation,
+or ``--sys-prefix`` to install to Python's prefix (e.g. in a virtual or conda environment).
 Where my_extension is the directory containing the Javascript files.
 This will copy it to a Jupyter data directory (the exact location is platform
 dependent - see :ref:`jupyter_path`).
@@ -214,11 +216,15 @@ For development, you can use the ``--symlink`` flag to symlink your extension
 rather than copying it, so there's no need to reinstall after changes.
 
 To use your extension, you'll also need to **enable** it, which tells the
-notebook interface to load it. You can do that with another command:
+notebook interface to load it. You can do that with another command::
 
-    jupyter nbextension enable my_extension/main
+    jupyter nbextension enable my_extension/main [--sys-prefix]
 
 The argument refers to the Javascript module containing your
 ``load_ipython_extension`` function, which is ``my_extension/main.js`` in this
 example. There is a corresponding ``disable`` command to stop using an
 extension without uninstalling it.
+
+.. versionchanged:: 4.2
+
+    Added ``--sys-prefix`` argument

docs/source/index.rst

@@ -36,8 +36,9 @@ The Jupyter notebook
    public_server
    security
    frontend_config
-   extending/index
-
+   examples/Notebook/rstversions/Distributing Jupyter Extensions as Python Packages.rst
+   extending/index.rst
+
 .. toctree::
    :maxdepth: 1
    :caption: Developer Documentation